getCampaign

The getCampaign call is used by the seller to retrieve a specific discount campaign.

Request Details

Pass in one campaignId value in the getCampaign request to retrieve the corresponding discount campaign.

Working with the Response

Upon a successful call, the entire campaign container for the specified discount campaign is returned in the response. If the campaign container is not returned, the caller will need to view any corresponding error messages in the response.

getCampaign Input

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).

getCampaign Output

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).

See also Samples.

<?xml version="1.0" encoding="utf-8"?>
<getCampaignResponse xmlns="http://www.ebay.com/marketplace/incentives/v1/services">
  <!-- Standard Output Fields -->
  <ack> AckValue </ack>
  <errorMessage> ErrorMessage </errorMessage>
  <timestamp> dateTime </timestamp>
  <version> string </version>
  <!-- Call-specific Output Fields -->
  <campaign> Campaign
    <budgetAmount currencyId="string"> Amount (double) </budgetAmount>
    <campaignId> long </campaignId>
    <campaignStatus> CampaignStatusEnum </campaignStatus>
    <campaignType> CampaignTypeEnum </campaignType>
    <description> string </description>
    <endDate> dateTime </endDate>
    <marketingPriority> int </marketingPriority>
    <name> string </name>
    <offer> Offer
      <buyerCondition> BuyerCondition
        <orderSize> SizeRange
          <fromSize> int </fromSize>
          <toSize> int </toSize>
        </orderSize>
        <orderTotal> AmountRange
          <fromAmount currencyId="string"> Amount (double) </fromAmount>
          <toAmount currencyId="string"> Amount (double) </toAmount>
        </orderTotal>
      </buyerCondition>
      <offerId> long </offerId>
      <sellerOffer> SellerOffer
        <discountOffer> DiscountOffer
          <discountAmount currencyId="string"> Amount (double) </discountAmount>
          <discountPercent> float </discountPercent>
          <discountQuantity> DiscountQuantity
            <applyToMaxPricedItems> boolean </applyToMaxPricedItems>
            <discountPercent> float </discountPercent>
            <discountQuantity> int </discountQuantity>
          </discountQuantity>
          <shippingDiscountPercent> float </shippingDiscountPercent>
        </discountOffer>
        <fixedAmountOffer> FixedAmountOffer
          <shippingTotalOffer> ShippingTotalOffer
            <shippingService> ShippingServiceEnum </shippingService>
            <!-- ... more shippingService nodes here ... -->
            <shippingTotalCost currencyId="string"> Amount (double) </shippingTotalCost>
          </shippingTotalOffer>
          <subTotalOrderAmount currencyId="string"> Amount (double) </subTotalOrderAmount>
        </fixedAmountOffer>
        <freeGiftSKUId> string </freeGiftSKUId>
        <!-- ... more freeGiftSKUId nodes here ... -->
      </sellerOffer>
      <status> OfferStatusEnum </status>
    </offer>
    <!-- ... more offer nodes here ... -->
    <restriction> Restriction
      <aspect> CatAspects
        <aspects> Aspect
          <name> string </name>
          <value> string </value>
        </aspects>
        <!-- ... more aspects nodes here ... -->
        <catId> long </catId>
      </aspect>
      <!-- ... more aspect nodes here ... -->
      <categoryId> long </categoryId>
      <restrictionType> ResrtrictionTypeEnum </restrictionType>
      <SKU> CatSKUs
        <catId> long </catId>
        <SKUs> string </SKUs>
      </SKU>
      <!-- ... more SKU nodes here ... -->
    </restriction>
    <!-- ... more restriction nodes here ... -->
    <stackSetId> long </stackSetId>
    <startDate> dateTime </startDate>
  </campaign>
</getCampaignResponse>

Return Value	Type	Occurrence	Meaning

Standard Output Fields [Jump to call-specific fields]

ack	AckValue	Always	A token representing the application-level acknowledgement code that indicates the response status.
errorMessage	ErrorMessage	Conditionally	Information for an error or warning that occurred when eBay processed the request. This field is not returned if the ack value is Success.
timestamp	dateTime	Always	This value represents the date and time when eBay processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See Time Values in the eBay Trading API Guide for information about this time format and converting to and from the GMT time zone.
version	string	Always	The version of the response payload schema. Indicates the version of the schema that eBay used to process the request.

Call-specific Output Fields

campaign	Campaign	Always	Root container of a discount campaign. One discount campaign is retrieved in a getCampaign call.
campaign.budgetAmount	Amount (double)	Conditionally	This field is for future use. Once implemented, this amount will indicate the maximum dollar amount of total discounts that the seller will allow to pass down to the buyers as part of the discount campaign. Once this amount is reached, the discount campaign will end.
campaign.budgetAmount [ attribute currencyId ]	string	Conditionally	This attribute identifies the currency in which the monetary amount is specified.
campaign.campaignId	long	Always	This value is the unique identifier of a discount campaign. A campaignId is created by eBay upon successful creation of a discount campaign, either through the site, or by using the createCampaigns call. Once created, a campaignId cannot be changed on the site or by using the updateCampaigns call.
campaign.campaignStatus	CampaignStatusEnum	Always	This enumeration value indicates the current status of a discount campaign. A CampaignStatusEnum value is required when using the setCampaignStatus call, and is optional when using the createCampaigns or updateCampaigns calls. In both update calls, the specified value will change the state of the existing discount campaign if the call is successful. In the createCampaigns call, the common use case is to create a new discount campaign and have that discount campaign automatically activated once the startDate is reached. For this use case, the campaignStatus field is not necessarily. However, there may a use case where a seller wants to create a new discount campaign, but does not want it active yet, even after the startDate is reached. In this case, the seller would include the campaignStatus field and set its value to ONHOLD or DRAFT. The campaignStatus field is always returned in the getCampaign and getCampaigns calls if matching discount campaign(s) are returned. Applicable values: • ACTIVE (in/out) This value indicates that the discount campaign is active. Typically, a seller would specify this value in the createCampaign call to create and activate the discount campaign, or in the updateCampaigns or setCampaignStatus calls to activate a disabled discount campaign. • DELETED (in/out) This value indicates that the discount campaign has been deleted. Typically, a seller would specify this value in the updateCampaigns or setCampaignStatus calls to delete a discount campaign. • DRAFT (in/out) This value indicates that the discount campaign is in "Draft" mode only, and will not become ACTIVE when the startDate value is reached. • ENDED (in/out) This value indicates that the life of the discount campaign has ended. The life of a discount campaign ends when the endDate dateTime value is reached. • ONHOLD (in/out) This value indicates that the discount campaign has been put on hold. Typically, a seller would specify this value in the updateCampaigns or setCampaignStatus calls to place an active discount campaign on hold. Discount campaigns in the ONHOLD state can be activated again. • SCHEDULED (in/out) This value indicates that the discount campaign is scheduled to become ACTIVE when the startDate dateTime value is reached.
campaign.campaignType	CampaignTypeEnum	Always	Enumerated value indicating if the discount campaign is generic or relational. If not specified in a createCampaigns, the campaign type defaults to GENERIC. In version 1.0.0 of this service, RELATIONAL is not supported. Applicable values: • GENERIC (in/out) This value indicates that the discount campaign is generic. • RELATIONAL (in/out) This value indicates that the discount campaign is relational. In version 1.0.0 of this service, RELATIONAL is not supported.
campaign.description	string	Conditionally	A description of the discount campaign. This is an optional field.
campaign.endDate	dateTime	Always	This dateTime value indicates the scheduled end time of a discount campaign. Once the endDate value is reached, the discount campaign becomes inactive on eBay and changes to the ENDED state. For the createCampaigns and updateCampaigns calls, endDate is a required field. The seller must pass the "date" part of the dateTime value in the following format: YYYY-mm-DD. The "time" part of the dateTime value automatically defaults to a local time (of the site implementing the discount campaign) of 23:59:59. The endDate value must be at least one day further into the future than the startDate value. For the getCampaign and getCampaigns calls, the endDate value is always returned for all discount campaigns that are successfully retrieved.
campaign.marketingPriority	int	Always	This field is for future use. This integer value controls (in request) or indicates (in response) the priority of the discount campaign in the product listings. The lowest integer value will have the highest priority. If the marketingPriority value(s) are not specified for discount campaigns, the discount campaign with the most refined inventory restrictions will display (e.g. a listing that qualifies for both a SKU-based offer and entire store offer will display the SKU-based offer).
campaign.name	string	Conditionally	The name of the discount campaign is an optional field that can help sellers to better manage their offers. The name has a limit of 30 characters. Max length: 30.
campaign.offer	Offer	Always, repeatable: [1..*]	Container consisting of seller discount offer details. A discount campaign can have multiple seller discount offers. Seller discount offer data is included in createCampaigns and updateCampaigns calls, and returned in getCampaign and getCampaigns calls.
campaign.offer.buyerCondition	BuyerCondition	Conditionally	Container consisting of the order requirements that must be met before a buyer is eligible for the corresponding discount offer. For each discount offer, a buyer condition will be based on number of items purchased, or based on the dollar value of the order. Based on the discount offer, this container is not always required.
campaign.offer.buyerCondition .orderSize	SizeRange	Conditionally	Container consisting of the number of line items that an order must contain in order for the buyer to qualify for the discount offer.
campaign.offer.buyerCondition .orderSize.fromSize	int	Conditionally	This integer value specifies the lower limit of the item number range. A buyer must purchase at least this many items for the order to qualify for the seller's discount. If the orderSize container is used, both the fromSize and toSize values must be set, and they can be the same value if the seller wants to require an exact number of items that must be purchased to qualify for the discount.
campaign.offer.buyerCondition .orderSize.toSize	int	Conditionally	This integer value specifies the upper limit of the item number range. A buyer can purchase no more than this number of items and still qualify for the seller's discount. If the orderSize container is used, both the fromSize and toSize values must be set, and they can be the same value if the seller wants to require an exact number of items that must be purchased to qualify for the discount.
campaign.offer.buyerCondition .orderTotal	AmountRange	Conditionally	Container consisting of the dollar range that an order's total value must be within in order for the buyer to qualify for the discount offer.
campaign.offer.buyerCondition .orderTotal.fromAmount	Amount (double)	Conditionally	This integer value specifies the lower limit of the dollar value range. The dollar value of the order must be at least this much to qualify for the seller's discount. If the orderTotal container is used, both the fromAmount and toAmount values must be set, and they can be the same value if the seller wants to require an exact dollar value an order must meet to qualify for the discount.
campaign.offer.buyerCondition .orderTotal.fromAmount [ attribute currencyId ]	string	Conditionally	This attribute identifies the currency in which the monetary amount is specified.
campaign.offer.buyerCondition .orderTotal.toAmount	Amount (double)	Conditionally	This integer value specifies the upper limit of the dollar value range. The dollar value of the order must not exceed this value to qualify for the seller's discount. If the orderTotal container is used, both the fromAmount and toAmount values must be set, and they can be the same value if the seller wants to require an exact dollar value an order must meet to qualify for the discount.
campaign.offer.buyerCondition .orderTotal.toAmount [ attribute currencyId ]	string	Conditionally	This attribute identifies the currency in which the monetary amount is specified.
campaign.offer.offerId	long	Always	This value is the unique identifier of a discount offer within a discount campaign. An offerId is created by eBay upon successful creation of a discount campaign, either through the site, or by using the createCampaigns call. Once created, an offerId cannot be changed on the site or by using the updateCampaigns call.
campaign.offer.sellerOffer	SellerOffer	Always	Container consisting of details related to the seller's offer.
campaign.offer.sellerOffer .discountOffer	DiscountOffer	Conditionally	Container consisting of details relating to a percentage or fixed amount discount.
campaign.offer.sellerOffer .discountOffer.discountAmount	Amount (double)	Conditionally	This dollar value specifies the amount of a fixed amount discount. The discountAmount value cannot exceed 80 percent of the buyerCondition.orderTotal.fromAmount value (if this value is set). For each discount offer, either a discountAmount, a discountPercent, or a discountQuantity value must be supplied.
campaign.offer.sellerOffer .discountOffer.discountAmount [ attribute currencyId ]	string	Conditionally	This attribute identifies the currency in which the monetary amount is specified.
campaign.offer.sellerOffer .discountOffer.discountPercent	float	Conditionally	This float value specifies the percentage discount that a buyer will receive on an order if buyer conditions are met. The discountPercent value cannot exceed 80 percent. Max: 80.
campaign.offer.sellerOffer .discountOffer .discountQuantity	DiscountQuantity	Conditionally	Container used to specify a 'Buy N items, get X% off Y of the item(s)' offer, such as 'Buy 2 items, get 50% off 1 of the items' or 'Buy 3 items, get 100% off 1 of the items (get 1 free). The number of items a buyer is required to buy is set in the buyerCondition.orderSize fields.
campaign.offer.sellerOffer .discountOffer .discountQuantity .applyToMaxPricedItems	boolean	Conditionally	This boolean value specifies whether or not the percentage discount on qualifying item(s) is applied to the highest priced item. This value is 'false' by default. Discounts are generally applied to the lowest priced item. Default: false.
campaign.offer.sellerOffer .discountOffer .discountQuantity .discountPercent	float	Conditionally	This float value specifies the percentage discount that a buyer will receive on qualifying item(s) within a single order if buyer conditions are met; in this case, the number of items purchased must satisfy the range specified in the buyerCondition.orderSize fields. The number of items receiving this discount is specified in the discountQuantity.discountQuantity field. This field is required if the discountQuantity container is used.
campaign.offer.sellerOffer .discountOffer .discountQuantity .discountQuantity	int	Conditionally	This integer value specifies the number of items that will receive the percentage discount specified in the discountQuantity.discountPercent field. This field is required if the discountQuantity container is used.
campaign.offer.sellerOffer .discountOffer .shippingDiscountPercent	float	Conditionally	This field is for future use.
campaign.offer.sellerOffer .fixedAmountOffer	FixedAmountOffer	Conditionally	This container is for future use.
campaign.offer.sellerOffer .fixedAmountOffer .shippingTotalOffer	ShippingTotalOffer	Conditionally	The shippingTotalOffer container and all of its children are for future use.
campaign.offer.sellerOffer .fixedAmountOffer .shippingTotalOffer .shippingService	ShippingServiceEnum	Conditionally, repeatable: [0..*]	This field is for future use. Applicable values: • PromotionaExpeditedShippingService (in/out) Enumerated value is for future use. • PromotionalEconomyShippingService (in/out) Enumerated value is for future use. • PromotionalOneDayShippingService (in/out) Enumerated value is for future use. • PromotionalStandardShippingService (in/out) Enumerated value is for future use.
campaign.offer.sellerOffer .fixedAmountOffer .shippingTotalOffer .shippingTotalCost	Amount (double)	Conditionally	This field is for future use.
campaign.offer.sellerOffer .fixedAmountOffer .shippingTotalOffer .shippingTotalCost [ attribute currencyId ]	string	Conditionally	This attribute identifies the currency in which the monetary amount is specified.
campaign.offer.sellerOffer .fixedAmountOffer .subTotalOrderAmount	Amount (double)	Conditionally	This field is for future use.
campaign.offer.sellerOffer .fixedAmountOffer .subTotalOrderAmount [ attribute currencyId ]	string	Conditionally	This attribute identifies the currency in which the monetary amount is specified.
campaign.offer.sellerOffer .freeGiftSKUId	string	Conditionally, repeatable: [0..*]	This field is for future use.
campaign.offer.status	OfferStatusEnum	Always	This enumeration value indicates the current status of a discount offer within a discount campaign. This field is typically used in a createCampaigns or updateCampaigns call if the seller wants to activate or delete specific discount offers within the discount campaign. The offer.status field is always returned in the getCampaign and getCampaigns calls if matching discount campaign(s) are returned. Applicable values: • ACTIVE (in/out) This value indicates that the discount offer is active. Typically, a seller would specify this value in the updateCampaigns call to activate a specific discount offer within a discount campaign. • DELETED (in/out) This value can be used in updateCampaigns to delete a specific discount offer. In getCampaign and getCampaigns calls, this value indicates that the discount offer has been deleted.
campaign.restriction	Restriction	Conditionally, repeatable: [0..*]	Container consisting of items (specified with SKUs), categories, or product attributes that should be excluded or included from a discount campaign. The RestrictionTypeEnum value controls whether these items, categories, or product attributes are included or excluded from the discount campaign.
campaign.restriction.aspect	CatAspects	Conditionally, repeatable: [0..*]	Container consisting of an eBay category ID and one or more product attribute pairs (aspects). The specified product attribute pairs listed in the specified category are included or excluded from a discount campaign based on the restrictionType value. eBay category IDs can be retrieved using the GetCategories Trading API call. Multiple aspect containers may be used.
campaign.restriction.aspect .aspects	Aspect	Conditionally, repeatable: [1..*]	Container consisting of a product attribute pair to include or exclude from a discount campaign. Multiple aspects containers may be used.
campaign.restriction.aspect .aspects.name	string	Conditionally	This string value indicates the name of the product attribute. This field must be specified (input) and is always returned (output) if product attribute(s) (aspects) are included/excluded from a discount campaign.
campaign.restriction.aspect .aspects.value	string	Conditionally	This string value indicates the value of the product attribute. This field must be specified (input) and is always returned (output) if product attribute(s) (aspects) are included/excluded from a discount campaign.
campaign.restriction.aspect .catId	long	Conditionally	The eBay category ID of the product attributes (aspects) to include or exclude from a discount campaign. eBay category IDs can be retrieved using the GetCategories Trading API call. catId is strictly optional as product attributes do not need to be associated with an eBay category ID.
campaign.restriction .categoryId	long	Conditionally	The eBay category ID to include or exclude from a discount campaign. eBay category IDs can be retrieved using the GetCategories Trading API call. Only a single categoryId value may be used.
campaign.restriction .restrictionType	ResrtrictionTypeEnum	Conditionally	Enumerated value indicating whether the items, categories, or product attributes included under the restriction container should be excluded from or included in a discount campaign. If a discount campaign contains a restriction container, restrictionType is always required (input) and returned (output). Applicable values: • EXCLUDE (in/out) This enumeration value is for future use. If the restrictionType value is EXCLUDE, all items, categories, and product attributes passed in the restriction container should be excluded (not eligible for discount) in the corresponding discount campaign. • INCLUDE (in/out) If the restrictionType value is INCLUDE, all items, categories, and product attributes passed in the restriction container should be included (eligible for discount) in the corresponding discount campaign.
campaign.restriction.SKU	CatSKUs	Conditionally, repeatable: [0..*]	Container consisting of an eBay category ID and one or more products (specified with SKU values) listed in the category specified by the category ID. The specified product(s) listed in the specified category are included or excluded from a discount campaign based on the restrictionType value. eBay category IDs can be retrieved using the GetCategories Trading API call. Multiple SKU containers may be used.
campaign.restriction.SKU.catId	long	Conditionally	The eBay category ID of the products to include or exclude from a discount campaign. eBay category IDs can be retrieved using the GetCategories Trading API call. catId is strictly optional as products (SKU values) do not need to be associated with an eBay category ID.
campaign.restriction.SKU.SKUs	string	Conditionally	The SKU value of the products to include or exclude from a discount campaign. It is optional whether the seller associates SKU values to an eBay category ID. Multiple SKUs may be listed in this field using a comma delimiter.
campaign.stackSetId	long	Always	This value is the unique identifier of a stack set. Once created, a stackSetId cannot be changed on the site or by using the updateCampaigns call.
campaign.startDate	dateTime	Always	This dateTime value indicates the scheduled start time of a discount campaign. Unless the discount campaign is in "draft" mode (CampaignStatusEnum=DRAFT), once the startDate value is reached, the discount campaign becomes active on eBay and remains active until the endDate value is reached, or until the discount campaign is deleted, ended, or put on hold on the site or through the updateCampaigns or setCampaignStatus calls. The following dateTime format is used: YYYY-mm-DDTHH:MM:SS. For the createCampaigns and updateCampaigns calls, startDate is a required field. The seller must pass the "date" part of the dateTime value in the following format: YYYY-mm-DD. The "time" part of the dateTime value automatically defaults to a local time (of the site implementing the discount campaign) of 23:59:59. For the getCampaign and getCampaigns calls, the startDate value is always returned for all discount campaigns that are successfully retrieved.

getCampaign Samples

getCampaign Change History

Version	Description
1.0.0 2011-09-14	(added) New call.

User-Contributed Notes

Order Size Discounts API Call Reference Version 1.0.0