"
- },
- "usage": {
- "type": "string",
- "description": "Whether the specified property is REQUIRED or OPTIONAL. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "An array that defines the configuration supported by this template. This includes specified properties and usage (whether the property is REQUIRED or OPTIONAL), and an optional default value."
- },
- "Task": {
- "type": "object",
- "properties": {
- "completionDate": {
- "type": "string",
- "description": "The timestamp when the task went into the COMPLETED or COMPLETED_WITH_ERROR state. This state means that eBay has compiled the report for the seller based on the sellerās filter criteria, and the seller can run a getResultFile call to download the report."
- },
- "creationDate": {
- "type": "string",
- "description": "The date the task was created."
- },
- "detailHref": {
- "type": "string",
- "description": "The path to the call URI used to retrieve the task. This field points to the GetOrderTask URI if the task is for LMS_ORDER_REPORT or will be null if this task is for LMS_ORDER_ACK."
- },
- "feedType": {
- "type": "string",
- "description": "The feed type associated with the task."
- },
- "schemaVersion": {
- "type": "string",
- "description": "The schema version number associated with the task."
- },
- "status": {
- "type": "string",
- "description": "The enumeration value that indicates the state of the task that was submitted in the request. See FeedStatusEnum for information. The values COMPLETED and COMPLETED_WITH_ERROR indicate the Order Report file is ready to download.
For implementation help, refer to eBay API documentation"
- },
- "taskId": {
- "type": "string",
- "description": "The ID of the task that was submitted in the request."
- },
- "uploadSummary": {
- "description": "This container provides summary information on an upload feed (not applicable for download feed types).",
- "$ref": "#/components/schemas/UploadSummary"
- }
- },
- "description": "The type that defines the fields for the task details."
- },
- "TaskCollection": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The path to the call URI that produced the current page of results. "
- },
- "limit": {
- "type": "integer",
- "description": "The value of the limit parameter submitted in the request, which is the maximum number of tasks to return per page, from the result set. A result set is the complete set of tasks returned by the method. Note: Though this parameter is not required to be submitted in the request, the parameter defaults to 10 if omitted.
Note: If this is the last or only page of the result set, the page may contain fewer tasks than the limit value. To determine the number of pages in a result set, divide the total value (total number of tasks matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total tasks) and the limit value was 50 (show 50 tasks per page), the total number of pages in the result set is three, so the seller would have to make three separate getTasks calls to view all tasks matching the input criteria.
",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The path to the call URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The path to the call URI for the previous page of results. This is returned if there is a previous page of results from the result set."
- },
- "tasks": {
- "type": "array",
- "description": "An array of the tasks on this page. The tasks are sorted by creation date. An empty array is returned if the filter criteria excludes all tasks. ",
- "items": {
- "$ref": "#/components/schemas/Task"
- }
- },
- "total": {
- "type": "integer",
- "description": "The total number of tasks that match the input criteria.",
- "format": "int32"
- }
- },
- "description": "The type that defines the fields for a paginated result set of tasks. The response consists of 0 or more sequenced pages where each page has 0 or more items."
- },
- "UpdateUserScheduleRequest": {
- "type": "object",
- "properties": {
- "preferredTriggerDayOfMonth": {
- "type": "integer",
- "description": "The preferred day of the month to trigger the schedule. This field can be used with preferredTriggerHour for monthly schedules. The last day of the month is used for numbers larger than the actual number of days in the month.
This field is available as specified by the template (scheduleTemplateId). The template can specify this field as optional or required, and optionally provides a default value.
Minimum: 1
Maximum: 31",
- "format": "int32"
- },
- "preferredTriggerDayOfWeek": {
- "type": "string",
- "description": "The preferred day of the week to trigger the schedule. This field can be used with preferredTriggerHour for weekly schedules.
This field is available as specified by the template (scheduleTemplateId). The template can specify this field as optional or required, and optionally provides a default value. For implementation help, refer to eBay API documentation"
- },
- "preferredTriggerHour": {
- "type": "string",
- "description": "The preferred two-digit hour of the day to trigger the schedule.
This field is available as specified by the template (scheduleTemplateId). The template can specify this field as optional or required, and optionally provides a default value.
Format: UTC hhZ
For example, the following represents 11:00 am UTC: 11Z
Minimum: 00Z
Maximum: 23Z"
- },
- "scheduleEndDate": {
- "type": "string",
- "description": "The timestamp on which the schedule (report generation) ends. After this date, the schedule status becomes INACTIVE.
Use this field, if available, to end the schedule in the future. This value must be later than scheduleStartDate (if supplied). This field is available as specified by the template (scheduleTemplateId). The template can specify this field as optional or required, and optionally provides a default value.
Format: UTC yyyy-MM-ddTHHZ
For example, the following represents UTC October 10, 2021 at 10:00 AM:
2021-10-10T10Z"
- },
- "scheduleName": {
- "type": "string",
- "description": "The schedule name assigned by the user for the created schedule."
- },
- "scheduleStartDate": {
- "type": "string",
- "description": "The timestamp to start generating the report. After this timestamp, the schedule status becomes active until either the scheduleEndDate occurs or the scheduleTemplateId becomes inactive.
Use this field, if available, to start the schedule in the future but before the scheduleEndDate (if supplied). This field is available as specified by the template (scheduleTemplateId). The template can specify this field as optional or required, and optionally provides a default value.
Format: UTC yyyy-MM-ddTHHZ
For example, the following represents a schedule start date of UTC October 01, 2020 at 12:00 PM:
2020-01-01T12Z"
- },
- "schemaVersion": {
- "type": "string",
- "description": "The schema version of the feedType for the schedule. This field is required if the feedType has a schema version.
This field is available as specified by the template (scheduleTemplateId). The template can specify this field as optional or required, and optionally provides a default value."
- }
- },
- "description": "The type that defines the fields for a schedule update to a schedule generated with the Feed API."
- },
- "UploadSummary": {
- "type": "object",
- "properties": {
- "failureCount": {
- "type": "integer",
- "description": "The number of records, such as the number of listings created or the number of pictures uploaded to a listing, that failed to process during the upload feed. Check the response file and correct any issues mentioned. If the feed fails before processing, no response file is provided. In this case check the REST output response.",
- "format": "int32"
- },
- "successCount": {
- "type": "integer",
- "description": "The number of records that were successfully processed during the upload feed.",
- "format": "int32"
- }
- },
- "description": "This container provides summary information on an upload feed (not applicable for download feed types)."
- },
- "UserScheduleCollection": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The path to the call URI that produced the current page of results."
- },
- "limit": {
- "type": "integer",
- "description": "The value of the limit parameter submitted in the request, which is the maximum number of schedules to return per page, from the result set. A result set is the complete set of schedules returned by the method. Note: Though this parameter is not required to be submitted in the request, the parameter defaults to 10 if omitted. Note: If this is the last or only page of the result set, the page may contain fewer tasks than the limit value. To determine the number of pages in a result set, divide the total value (total number of tasks matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total tasks) and the limit value was 50 (show 50 tasks per page), the total number of pages in the result set is three, so the seller would have to make three separate getSchedules calls to view all tasks matching the input criteria.
",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The path to the call URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The path to the call URI for the previous page of results. This is returned if there is a previous page of results from the result set."
- },
- "schedules": {
- "type": "array",
- "description": "An array of the schedules on this page. An empty array is returned if the filter criteria excludes all tasks.",
- "items": {
- "$ref": "#/components/schemas/UserScheduleResponse"
+ "OrderFilterCriteria": {
+ "type": "object",
+ "properties": {
+ "creationDateRange": {
+ "description": "The creation date range of the orders you want returned. Set the date range so it contains less than 10 days (maximum). If you do not specify a DateRange, results from the last 10 days will be returned by default.",
+ "$ref": "#/components/schemas/DateRange"
+ },
+ "modifiedDateRange": {
+ "description": "The modified date range of the orders you want returned. Note: This container is for future use. At this time, the createOrderTask method only supports order creation date filters and not modified order date filters.
",
+ "$ref": "#/components/schemas/DateRange"
+ },
+ "orderStatus": {
+ "type": "string",
+ "description": "The order status of the orders returned. If the filter is omitted from createOrderTask call, orders that are in both ACTIVE and COMPLETED states are returned. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "The type that defines the fields for the order filters."
+ },
+ "OrderTask": {
+ "type": "object",
+ "properties": {
+ "completionDate": {
+ "type": "string",
+ "description": "The timestamp when the task went into the COMPLETED or COMPLETED_WITH_ERROR state. This state means that eBay has compiled the report for the seller based on the sellerās filter criteria, and the seller can run a getResultFile call to download the report."
+ },
+ "creationDate": {
+ "type": "string",
+ "description": "The date the task was created."
+ },
+ "detailHref": {
+ "type": "string",
+ "description": "The path to the call URI used to retrieve the task."
+ },
+ "feedType": {
+ "type": "string",
+ "description": "The feed type associated with the task."
+ },
+ "filterCriteria": {
+ "description": "A container that returns the filter criteria used.",
+ "$ref": "#/components/schemas/OrderFilterCriteria"
+ },
+ "schemaVersion": {
+ "type": "string",
+ "description": "The schema version number associated with the create task."
+ },
+ "status": {
+ "type": "string",
+ "description": "The enumeration value that indicates the state of the task that was submitted in the request. See FeedStatusEnum for information. The values COMPLETED and COMPLETED_WITH_ERROR indicate the Order Report file is ready to download.
For implementation help, refer to eBay API documentation"
+ },
+ "taskId": {
+ "type": "string",
+ "description": "The ID of the task that was submitted in the request."
+ },
+ "uploadSummary": {
+ "description": "This container provides summary information on an upload feed (not applicable for download feed types).",
+ "$ref": "#/components/schemas/UploadSummary"
+ }
+ },
+ "description": "The type that defines the fields for the getOrderTask response."
+ },
+ "OrderTaskCollection": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The path to the call URI that produced the current page of results."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The value of the limit parameter submitted in the request, which is the maximum number of order tasks to return per page, from the result set. A result set is the complete set of tasks returned by the method. Note: Though this parameter is not required to be submitted in the request, the parameter defaults to 10 if omitted.
Note: If this is the last or only page of the result set, the page may contain fewer tasks than the limit value. To determine the number of pages in a result set, divide the total value (total number of tasks matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total tasks) and the limit value was 50 (show 50 tasks per page), the total number of pages in the result set is three, so the seller would have to make three separate getOrderTasks calls to view all tasks matching the input criteria.
",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The path to the call URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The path to the call URI for the previous page of results. This is returned if there is a previous page of results from the result set."
+ },
+ "tasks": {
+ "type": "array",
+ "description": "An array of the order tasks on this page. The tasks are sorted by creation date. An empty array is returned if the filter criteria excludes all tasks.",
+ "items": {
+ "$ref": "#/components/schemas/OrderTask"
+ }
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of order tasks that match the input criteria.",
+ "format": "int32"
+ }
+ },
+ "description": "The type that defines the fields for a paginated result set of orders. The response consists of 0 or more sequenced pages where each page has 0 or more items."
+ },
+ "ScheduleTemplateCollection": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The path to the call URI that produced the current page of results."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The value of the limit parameter submitted in the request, which is the maximum number of schedule templates to return per page, from the result set. A result set is the complete set of schedule templates returned by the method. Note: Though this parameter is not required to be submitted in the request, the parameter defaults to 10 if omitted.
Note: If this is the last or only page of the result set, the page may contain fewer tasks than the limit value. To determine the number of pages in a result set, divide the total value (total number of tasks matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total tasks) and the limit value was 50 (show 50 tasks per page), the total number of pages in the result set is three, so the seller would have to make three separate getScheduleTemplates calls to view all tasks matching the input criteria.
",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The path to the call URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The path to the call URI for the previous page of results. This is returned if there is a previous page of results from the result set."
+ },
+ "scheduleTemplates": {
+ "type": "array",
+ "description": "An array of the schedule templates on this page. An empty array is returned if the filter criteria excludes all tasks.",
+ "items": {
+ "$ref": "#/components/schemas/ScheduleTemplateResponse"
+ }
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of schedule templates that match the input criteria.",
+ "format": "int32"
+ }
+ },
+ "description": "The type that defines the fields for a paginated result set of schedule templates. The response consists of 0 or more sequenced pages where each page has 0 or more items."
+ },
+ "ScheduleTemplateResponse": {
+ "type": "object",
+ "properties": {
+ "feedType": {
+ "type": "string",
+ "description": "The feed type of the schedule template. Note: When calling createSchedule and updateSchedule methods you must match the feed type specified by the schedule template (this feedType).
"
+ },
+ "frequency": {
+ "type": "string",
+ "description": "This field specifies how often the schedule is generated. If set to HALF_HOUR or ONE_HOUR, you cannot set a preferredTriggerHour using createSchedule or updateSchedule. For implementation help, refer to eBay API documentation"
+ },
+ "name": {
+ "type": "string",
+ "description": "The template name provided by the template."
+ },
+ "scheduleTemplateId": {
+ "type": "string",
+ "description": "The ID of the template. Use this ID to create a schedule based on the properties of this schedule template."
+ },
+ "status": {
+ "type": "string",
+ "description": "The present status of the template. You cannot create or modify a schedule using a template with an INACTIVE status. For implementation help, refer to eBay API documentation"
+ },
+ "supportedConfigurations": {
+ "type": "array",
+ "description": "An array of the configuration supported by this template.",
+ "items": {
+ "$ref": "#/components/schemas/SupportedConfiguration"
+ }
+ }
+ },
+ "description": "The type that defines the fields for a paginated result set of available schedule templates. The response consists of 0 or more sequenced pages where each page has 0 or more items."
+ },
+ "ServiceMetricsTask": {
+ "type": "object",
+ "properties": {
+ "completionDate": {
+ "type": "string",
+ "description": "The timestamp when the customer service metrics task went into the COMPLETED or COMPLETED_WITH_ERROR state. This field is only returned if the status is one of the two completed values. This state means that eBay has compiled the report for the seller based on the sellerās filter criteria, and the seller can run a getResultFile call to download the report."
+ },
+ "creationDate": {
+ "type": "string",
+ "description": "The date the customer service metrics task was created."
+ },
+ "detailHref": {
+ "type": "string",
+ "description": "The relative getCustomerServiceMetricTask call URI path to retrieve the corresponding task."
+ },
+ "feedType": {
+ "type": "string",
+ "description": "The feed type associated with the task."
+ },
+ "filterCriteria": {
+ "description": "This container shows the criteria set for the report.",
+ "$ref": "#/components/schemas/CustomerServiceMetricsFilterCriteria"
+ },
+ "schemaVersion": {
+ "type": "string",
+ "description": "The schema version number of the file format. If omitted, the default value is used. Default value: 1.0
"
+ },
+ "status": {
+ "type": "string",
+ "description": "An enumeration value that indicates the state of the task. See FeedStatusEnum for values. For implementation help, refer to eBay API documentation"
+ },
+ "taskId": {
+ "type": "string",
+ "description": "The unique eBay-assigned ID of the task."
+ }
+ },
+ "description": "This type defines customer service metric task response fields."
+ },
+ "StreamingOutput": {
+ "type": "object",
+ "description": "File stream"
+ },
+ "SupportedConfiguration": {
+ "type": "object",
+ "properties": {
+ "defaultValue": {
+ "type": "string",
+ "description": "The default value for the property. If a value is omitted from the schedule and a default value is supplied, the default value is used."
+ },
+ "property": {
+ "type": "string",
+ "description": "Properties supported by the template. Properties can include the following:
- scheduleStartDate: The timestamp that the report generation (subscription) begins. After this timestamp, the schedule status becomes active until either the scheduleEndDate occurs or the scheduleTemplate becomes inactive. Format: UTC
yyyy-MM-ddTHHZ - scheduleEndDate: The timestamp that the report generation (subscription) ends. After this date, the schedule status becomes INACTIVE. Format: UTC
yyyy-MM-ddTHHZ - schemaVersion: The schema version of the schedule templates feedType. This field is required if the feedType has a schema version.
- preferredTriggerDayOfMonth: The preferred day of the month to trigger the schedule.
- preferredTriggerDayOfWeek: The preferred day of the week to trigger the schedule.
- preferredTriggerHour: The preferred two-digit hour of the day to trigger the schedule. Format: UTC
hhZ "
+ },
+ "usage": {
+ "type": "string",
+ "description": "Whether the specified property is REQUIRED or OPTIONAL. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "An array that defines the configuration supported by this template. This includes specified properties and usage (whether the property is REQUIRED or OPTIONAL), and an optional default value."
+ },
+ "Task": {
+ "type": "object",
+ "properties": {
+ "completionDate": {
+ "type": "string",
+ "description": "The timestamp when the task went into the COMPLETED or COMPLETED_WITH_ERROR state. This state means that eBay has compiled the report for the seller based on the sellerās filter criteria, and the seller can run a getResultFile call to download the report."
+ },
+ "creationDate": {
+ "type": "string",
+ "description": "The date the task was created."
+ },
+ "detailHref": {
+ "type": "string",
+ "description": "The path to the call URI used to retrieve the task. This field points to the GetOrderTask URI if the task is for LMS_ORDER_REPORT or will be null if this task is for LMS_ORDER_ACK."
+ },
+ "feedType": {
+ "type": "string",
+ "description": "The feed type associated with the task."
+ },
+ "schemaVersion": {
+ "type": "string",
+ "description": "The schema version number associated with the task."
+ },
+ "status": {
+ "type": "string",
+ "description": "The enumeration value that indicates the state of the task that was submitted in the request. See FeedStatusEnum for information. The values COMPLETED and COMPLETED_WITH_ERROR indicate the Order Report file is ready to download.
For implementation help, refer to eBay API documentation"
+ },
+ "taskId": {
+ "type": "string",
+ "description": "The ID of the task that was submitted in the request."
+ },
+ "uploadSummary": {
+ "description": "This container provides summary information on an upload feed (not applicable for download feed types).",
+ "$ref": "#/components/schemas/UploadSummary"
+ }
+ },
+ "description": "The type that defines the fields for the task details."
+ },
+ "TaskCollection": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The path to the call URI that produced the current page of results. "
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The value of the limit parameter submitted in the request, which is the maximum number of tasks to return per page, from the result set. A result set is the complete set of tasks returned by the method. Note: Though this parameter is not required to be submitted in the request, the parameter defaults to 10 if omitted.
Note: If this is the last or only page of the result set, the page may contain fewer tasks than the limit value. To determine the number of pages in a result set, divide the total value (total number of tasks matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total tasks) and the limit value was 50 (show 50 tasks per page), the total number of pages in the result set is three, so the seller would have to make three separate getTasks calls to view all tasks matching the input criteria.
",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The path to the call URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The path to the call URI for the previous page of results. This is returned if there is a previous page of results from the result set."
+ },
+ "tasks": {
+ "type": "array",
+ "description": "An array of the tasks on this page. The tasks are sorted by creation date. An empty array is returned if the filter criteria excludes all tasks. ",
+ "items": {
+ "$ref": "#/components/schemas/Task"
+ }
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of tasks that match the input criteria.",
+ "format": "int32"
+ }
+ },
+ "description": "The type that defines the fields for a paginated result set of tasks. The response consists of 0 or more sequenced pages where each page has 0 or more items."
+ },
+ "UpdateUserScheduleRequest": {
+ "type": "object",
+ "properties": {
+ "preferredTriggerDayOfMonth": {
+ "type": "integer",
+ "description": "The preferred day of the month to trigger the schedule. This field can be used with preferredTriggerHour for monthly schedules. The last day of the month is used for numbers larger than the actual number of days in the month.
This field is available as specified by the template (scheduleTemplateId). The template can specify this field as optional or required, and optionally provides a default value.
Minimum: 1
Maximum: 31",
+ "format": "int32"
+ },
+ "preferredTriggerDayOfWeek": {
+ "type": "string",
+ "description": "The preferred day of the week to trigger the schedule. This field can be used with preferredTriggerHour for weekly schedules.
This field is available as specified by the template (scheduleTemplateId). The template can specify this field as optional or required, and optionally provides a default value. For implementation help, refer to eBay API documentation"
+ },
+ "preferredTriggerHour": {
+ "type": "string",
+ "description": "The preferred two-digit hour of the day to trigger the schedule.
This field is available as specified by the template (scheduleTemplateId). The template can specify this field as optional or required, and optionally provides a default value.
Format: UTC hhZ
For example, the following represents 11:00 am UTC: 11Z
Minimum: 00Z
Maximum: 23Z"
+ },
+ "scheduleEndDate": {
+ "type": "string",
+ "description": "The timestamp on which the schedule (report generation) ends. After this date, the schedule status becomes INACTIVE.
Use this field, if available, to end the schedule in the future. This value must be later than scheduleStartDate (if supplied). This field is available as specified by the template (scheduleTemplateId). The template can specify this field as optional or required, and optionally provides a default value.
Format: UTC yyyy-MM-ddTHHZ
For example, the following represents UTC October 10, 2021 at 10:00 AM:
2021-10-10T10Z"
+ },
+ "scheduleName": {
+ "type": "string",
+ "description": "The schedule name assigned by the user for the created schedule."
+ },
+ "scheduleStartDate": {
+ "type": "string",
+ "description": "The timestamp to start generating the report. After this timestamp, the schedule status becomes active until either the scheduleEndDate occurs or the scheduleTemplateId becomes inactive.
Use this field, if available, to start the schedule in the future but before the scheduleEndDate (if supplied). This field is available as specified by the template (scheduleTemplateId). The template can specify this field as optional or required, and optionally provides a default value.
Format: UTC yyyy-MM-ddTHHZ
For example, the following represents a schedule start date of UTC October 01, 2020 at 12:00 PM:
2020-01-01T12Z"
+ },
+ "schemaVersion": {
+ "type": "string",
+ "description": "The schema version of a schedule."
+ }
+ },
+ "description": "The type that defines the fields for a schedule update to a schedule generated with the Feed API."
+ },
+ "UploadSummary": {
+ "type": "object",
+ "properties": {
+ "failureCount": {
+ "type": "integer",
+ "description": "The number of records, such as the number of listings created or the number of pictures uploaded to a listing, that failed to process during the upload feed. Check the response file and correct any issues mentioned. If the feed fails before processing, no response file is provided. In this case check the REST output response.",
+ "format": "int32"
+ },
+ "successCount": {
+ "type": "integer",
+ "description": "The number of records that were successfully processed during the upload feed.",
+ "format": "int32"
+ }
+ },
+ "description": "This container provides summary information on an upload feed (not applicable for download feed types)."
+ },
+ "UserScheduleCollection": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The path to the call URI that produced the current page of results."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The value of the limit parameter submitted in the request, which is the maximum number of schedules to return per page, from the result set. A result set is the complete set of schedules returned by the method. Note: Though this parameter is not required to be submitted in the request, the parameter defaults to 10 if omitted. Note: If this is the last or only page of the result set, the page may contain fewer tasks than the limit value. To determine the number of pages in a result set, divide the total value (total number of tasks matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total tasks) and the limit value was 50 (show 50 tasks per page), the total number of pages in the result set is three, so the seller would have to make three separate getSchedules calls to view all tasks matching the input criteria.
",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The path to the call URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The path to the call URI for the previous page of results. This is returned if there is a previous page of results from the result set."
+ },
+ "schedules": {
+ "type": "array",
+ "description": "An array of the schedules on this page. An empty array is returned if the filter criteria excludes all tasks.",
+ "items": {
+ "$ref": "#/components/schemas/UserScheduleResponse"
+ }
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of schedules that match the input criteria.",
+ "format": "int32"
+ }
+ },
+ "description": "The type that defines the fields for a paginated result set of user schedules. The response consists of 0 or more sequenced pages where each page has 0 or more items."
+ },
+ "UserScheduleResponse": {
+ "type": "object",
+ "properties": {
+ "scheduleId": {
+ "type": "string",
+ "description": "The ID of the schedule. This ID is generated when the schedule was created by the createSchedule method."
+ },
+ "creationDate": {
+ "type": "string",
+ "description": "The creation date of the schedule in hours based on the 24-hour Coordinated Universal Time (UTC) clock."
+ },
+ "feedType": {
+ "type": "string",
+ "description": "The feedType associated with the schedule."
+ },
+ "lastModifiedDate": {
+ "type": "string",
+ "description": "The date the schedule was last modified."
+ },
+ "preferredTriggerDayOfMonth": {
+ "type": "integer",
+ "description": "The preferred day of the month to trigger the schedule. This field can be used with preferredTriggerHour for monthly schedules. The last day of the month is used for numbers larger than the number of days in the month.",
+ "format": "int32"
+ },
+ "preferredTriggerDayOfWeek": {
+ "type": "string",
+ "description": "The preferred day of the week to trigger the schedule. This field can be used with preferredTriggerHour for weekly schedules. For implementation help, refer to eBay API documentation"
+ },
+ "preferredTriggerHour": {
+ "type": "string",
+ "description": "The preferred two-digit hour of the day to trigger the schedule.
Format: UTC hhZ
For example, the following represents 11:00 am UTC:
11Z
"
+ },
+ "scheduleEndDate": {
+ "type": "string",
+ "description": "The timestamp on which the report generation (subscription) ends. After this date, the schedule status becomes INACTIVE."
+ },
+ "scheduleName": {
+ "type": "string",
+ "description": "The schedule name assigned by the user for the created schedule. Users assign this name for their reference."
+ },
+ "scheduleStartDate": {
+ "type": "string",
+ "description": "The timestamp that indicates the start of the report generation."
+ },
+ "scheduleTemplateId": {
+ "type": "string",
+ "description": "The ID of the template used to create this schedule."
+ },
+ "schemaVersion": {
+ "type": "string",
+ "description": "The schema version of the feedType for the schedule."
+ },
+ "status": {
+ "type": "string",
+ "description": "The enumeration value that indicates the state of the schedule. For implementation help, refer to eBay API documentation"
+ },
+ "statusReason": {
+ "type": "string",
+ "description": "The reason the schedule is inactive. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "The type that defines the fields for a paginated result set of available schedules. The response consists of 0 or more sequenced pages where each page has 0 or more items."
}
- },
- "total": {
- "type": "integer",
- "description": "The total number of schedules that match the input criteria.",
- "format": "int32"
- }
},
- "description": "The type that defines the fields for a paginated result set of user schedules. The response consists of 0 or more sequenced pages where each page has 0 or more items."
- },
- "UserScheduleResponse": {
- "type": "object",
- "properties": {
- "scheduleId": {
- "type": "string",
- "description": "The ID of the schedule. This ID is generated when the schedule was created by the createSchedule method."
- },
- "creationDate": {
- "type": "string",
- "description": "The creation date of the schedule in hours based on the 24-hour Coordinated Universal Time (UTC) clock."
- },
- "feedType": {
- "type": "string",
- "description": "The feedType associated with the schedule."
- },
- "lastModifiedDate": {
- "type": "string",
- "description": "The date the schedule was last modified."
- },
- "preferredTriggerDayOfMonth": {
- "type": "integer",
- "description": "The preferred day of the month to trigger the schedule. This field can be used with preferredTriggerHour for monthly schedules. The last day of the month is used for numbers larger than the number of days in the month.",
- "format": "int32"
- },
- "preferredTriggerDayOfWeek": {
- "type": "string",
- "description": "The preferred day of the week to trigger the schedule. This field can be used with preferredTriggerHour for weekly schedules. For implementation help, refer to eBay API documentation"
- },
- "preferredTriggerHour": {
- "type": "string",
- "description": "The preferred two-digit hour of the day to trigger the schedule.
Format: UTC hhZ
For example, the following represents 11:00 am UTC:
11Z
"
- },
- "scheduleEndDate": {
- "type": "string",
- "description": "The timestamp on which the report generation (subscription) ends. After this date, the schedule status becomes INACTIVE."
- },
- "scheduleName": {
- "type": "string",
- "description": "The schedule name assigned by the user for the created schedule. Users assign this name for their reference."
- },
- "scheduleStartDate": {
- "type": "string",
- "description": "The timestamp that indicates the start of the report generation."
- },
- "scheduleTemplateId": {
- "type": "string",
- "description": "The ID of the template used to create this schedule."
- },
- "schemaVersion": {
- "type": "string",
- "description": "The schema version of the feedType for the schedule."
- },
- "status": {
- "type": "string",
- "description": "The enumeration value that indicates the state of the schedule. For implementation help, refer to eBay API documentation"
- },
- "statusReason": {
- "type": "string",
- "description": "The reason the schedule is inactive. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "The type that defines the fields for a paginated result set of available schedules. The response consists of 0 or more sequenced pages where each page has 0 or more items."
- }
- },
- "securitySchemes": {
- "api_auth": {
- "type": "oauth2",
- "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
- "flows": {
- "authorizationCode": {
- "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
- "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
- "scopes": {
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment": "View and manage your order fulfillments",
- "https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly": " This scope would allow signed in user to read catalog data.",
- "https://api.ebay.com/oauth/api_scope/sell.inventory": "View and manage your inventory and offers",
- "https://api.ebay.com/oauth/api_scope/sell.marketing": "View and manage your eBay marketing activities, such as ad campaigns and listing promotions",
- "https://api.ebay.com/oauth/api_scope/sell.analytics.readonly": "View your selling analytics data, such as performance reports"
+ "securitySchemes": {
+ "api_auth": {
+ "type": "oauth2",
+ "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
+ "flows": {
+ "authorizationCode": {
+ "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
+ "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
+ "scopes": {
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment": "View and manage your order fulfillments",
+ "https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly": " This scope would allow signed in user to read catalog data.",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory": "View and manage your inventory and offers",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing": "View and manage your eBay marketing activities, such as ad campaigns and listing promotions",
+ "https://api.ebay.com/oauth/api_scope/sell.analytics.readonly": "View your selling analytics data, such as performance reports"
+ }
+ }
+ }
}
- }
}
- }
}
- }
}
\ No newline at end of file
diff --git a/specs/sell_finances_v1_oas3.json b/specs/sell_finances_v1_oas3.json
index 5660860b..143f0507 100644
--- a/specs/sell_finances_v1_oas3.json
+++ b/specs/sell_finances_v1_oas3.json
@@ -1,1260 +1,2270 @@
{
- "openapi": "3.0.0",
- "info": {
- "title": "eBay Finances API",
- "description": "This API is used to retrieve seller payouts and monetary transaction details related to those payouts.",
- "contact": {
- "name": "eBay Inc,"
- },
- "license": {
- "name": "eBay API License Agreement",
- "url": "https://go.developer.ebay.com/api-license-agreement"
+ "openapi": "3.0.0",
+ "info": {
+ "title": "Finances API",
+ "description": "This API is used to retrieve seller payouts and monetary transaction details related to those payouts.",
+ "contact": {
+ "name": "eBay Inc,"
+ },
+ "license": {
+ "name": "eBay API License Agreement",
+ "url": "https://developer.ebay.com/join/api-license-agreement"
+ },
+ "version": "v1.19.0"
},
- "version": "1.9.0"
- },
- "servers": [
- {
- "url": "https://apiz.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/finances/v1"
- }
- }
- }
- ],
- "paths": {
- "/payout/{payout_Id}": {
- "get": {
- "tags": [
- "payout"
- ],
- "description": "This method retrieves details on a specific seller payout. The unique identfier of the payout is passed in as a path parameter at the end of the call URI.
The getPayouts method can be used to retrieve the unique identifier of a payout, or the user can check Seller Hub.",
- "operationId": "getPayout",
- "parameters": [
- {
- "name": "payout_Id",
- "in": "path",
- "description": "The unique identfier of the payout is passed in as a path parameter at the end of the call URI.
The getPayouts method can be used to retrieve the unique identifier of a payout, or the user can check Seller Hub to get the payout ID.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Payout"
+ "servers": [
+ {
+ "url": "https://apiz.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/finances/v1"
}
- }
}
- },
- "400": {
- "description": "Bad Request"
- },
- "404": {
- "description": "Not found",
- "x-response-codes": {
- "errors": {
- "135001": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The payout id was not found."
+ },
+ {
+ "url": "https://api.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/finances/v1"
}
- }
}
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "135000": {
- "domain": "API_FINANCES",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
+ }
+ ],
+ "paths": {
+ "/order_earnings": {
+ "get": {
+ "tags": [
+ "order_earnings"
+ ],
+ "description": "This method returns detailed order-level financial data for each order associated with a seller account. The returned order-level financial data includes order earnings, gross amount, expenses, and refunds. Order earnings includes earnings after deducting expenses and refunds from the gross amount.
Note: Expenses include fees, shipping labels, and donations. Refunds include gross refunds, gross claims, and gross payment disputes.
The financial data for orders will be returned as filtered based on the order's creation date. Note: Only charges and credits tied to the order are shown, and they appear in near real time for orders created within the selected order creation time window.
Pagination is supported through the limit and offset parameters. These parameters can be used to control the number of records returned in a single response and to retrieve subsequent pages of results when the result set spans multiple pages.
The response can be filtered by using the filter parameter. This parameter allows consumers to restrict the results returned by the method based on supported filtering criteria.
Note: Access to the order_earnings resource is currently limited to only US, China, or Hong Kong sellers who meet the following criteria and also request access:
- US sellers with the country of residence set to US and having a payout currency in USD.
- Hong Kong or China sellers having the country of residence set to HK or CN and the payout currency set to USD have access.
To request access, submit an application growth check to have the required OAuth scope added to your app. After submission, you can use the same growth check link to track the status of the request.
eBay plans on expanding this to other markets in the future.
Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
",
+ "operationId": "getOrderEarnings",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See HTTP request headers for the marketplace ID values.
Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This parameter can be used to filter orders created within a specified date range. The filter uses the orderCreationDate field, which works similarly to the transactionDate filter used by the Transactions API. Currently, orderCreationDate is the only supported filter value. Note: All dates must be input using UTC format (YYYY-MM-DDTHH:MM:SS.SSSZ) and should be adjusted accordingly for the local timezone of the user.
Default: If no value is specified, results from the past year will be returned.
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:FilterField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "This parameter configures the number of orders to return per page of the result set. Use this parameter in conjunction with the offset parameter to control the pagination of the output.
For example, if offset is set to 10 and limit is set to 10, the method retrieves orders 11 thru 20 from the result set.
Note: This feature employs a zero-based list, where the first page in the results set has an offset value of 0.
Maximum: 200
Default: 20",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "This parameter can be used to specify the number of records to skip before returning results. This parameter is commonly used with the limit parameter to retrieve the next page of results.
Maximum: 10,000
Default: 0",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sort",
+ "in": "query",
+ "description": "This parameter can be used to specify the sort order of the results. Currently, sorting is supported by order creation date.
Default: Results returned in ascending order sorted by orderCreationDate, with earliest creation date first. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:SortField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/OrderEarnings"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "135005": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of sort is invalid."
+ },
+ "135017": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of offset is invalid."
+ },
+ "135018": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of limit is invalid."
+ },
+ "135019": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The orderCreationDate filter is invalid due to syntax issue, or the start and end dates are not compatible with one another. Please see documentation."
+ },
+ "135020": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied date range is invalid, as orders before year 2024 cannot be retrieved. Please update the date range and resubmit the request."
+ },
+ "135021": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied date range is invalid, as the date range cannot exceed 12 months. Please update the date range and resubmit the request."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "135000": {
+ "domain": "API_FINANCES",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances.earnings.read"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.finances"
- ]
- }
- ]
- }
- },
- "/payout": {
- "get": {
- "tags": [
- "payout"
- ],
- "description": "This method is used to retrieve the details of one or more seller payouts. By using the filter query parameter, users can retrieve payouts processed within a specific date range, and/or they can retrieve payouts in a specific state.
There are also pagination and sort query parameters that allow users to control the payouts that are returned in the response.
If no payouts match the input criteria, an empty payload is returned.",
- "operationId": "getPayouts",
- "parameters": [
- {
- "name": "filter",
- "in": "query",
- "description": "The three filter types that can be used here are discussed below. If none of these filters are used, all recent payouts in all states are returned:- payoutDate: search for payouts within a specific range of dates. The date format to use is
YYYY-MM-DDTHH:MM:SS.SSSZ. Below is the proper syntax to use if filtering by a date range:
https://apiz.ebay.com/sell/finances/v1/payout?filter=payoutDate:[2018-12-17T00:00:01.000Z..2018-12-24T00:00:01.000Z]
Alternatively, the user could omit the ending date, and the date range would include the starting date and up to 90 days past that date, or the current date if the starting date is less than 90 days in the past. - lastAttemptedPayoutDate: search for attempted payouts that failed within a specific range of dates. In order to use this filter, the payoutStatus filter must also be used and its value must be set to
RETRYABLE_FAILED. The date format to use is YYYY-MM-DDTHH:MM:SS.SSSZ. The same syntax used for the payoutDate filter is also used for the lastAttemptedPayoutDate filter.
This filter is only applicable (and will return results) if one or more seller payouts have failed, but are retryable. - payoutStatus: search for payouts in a particular state. Only one payout state can be specified with this filter. The supported payoutStatus values are as follows:
INITIATED: search for payouts that have been initiated but not processed.SUCCEEDED: search for successful payouts.RETRYABLE_FAILED: search for payouts that failed, but ones which will be tried again. This value must be used if filtering by lastAttemptedPayoutDate. TERMINAL_FAILED: search for payouts that failed, and ones that will not be tried again.-
REVERSED: search for payouts that were reversed.
Below is the proper syntax to use if filtering by payout status:
https://apiz.ebay.com/sell/finances/v1/payout?filter=payoutStatus:{SUCCEEDED}
If both the payoutDate and payoutStatus filters are used, payouts must satisfy both criteria to be returned. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:FilterField",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "sort",
- "in": "query",
- "description": "By default, payouts or failed payouts that match the input criteria are sorted in ascending order according to the payout date/last attempted payout date (oldest payouts returned first).
To view payouts in descending order instead (most recent payouts/attempted payouts first), you would include the sort query parameter, and then set the value of its field parameter to payoutDate or lastAttemptedPayoutDate (if searching for failed, retrybable payouts). Below is the proper syntax to use if filtering by a payout date range in descending order:
https://apiz.ebay.com/sell/finances/v1/payout?filter=payoutDate:[2018-12-17T00:00:01.000Z..2018-12-24T00:00:01.000Z]&sort=payoutDate
Payouts can only be sorted according to payout date, and can not be sorted by payout status. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:SortField",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "limit",
- "in": "query",
- "description": "The number of payouts to return per page of the result set. Use this parameter in conjunction with the offset parameter to control the pagination of the output.
For example, if offset is set to 10 and limit is set to 10, the method retrieves payouts 11 thru 20 from the result set.
Note: This feature employs a zero-based list, where the first payout in the results set has an offset value of 0.
Maximum: 200
Default: 20",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "This integer value indicates the actual position that the first payout returned on the current page has in the results set. So, if you wanted to view the 11th payout of the result set, you would set the offset value in the request to 10.
In the request, you can use the offset parameter in conjunction with the limit parameter to control the pagination of the output. For example, if offset is set to 30 and limit is set to 10, the method retrieves payouts 31 thru 40 from the resulting collection of payouts.
Note: This feature employs a zero-based list, where the first payout in the results set has an offset value of 0.
Default: 0 (zero)",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Payouts"
- }
- }
+ "/order_earnings/{order_id}": {
+ "get": {
+ "tags": [
+ "order_earnings"
+ ],
+ "description": "This method returns detailed order-level financial data including order earnings, gross amount, expenses, and refunds. Order earnings includes earnings after deducting expenses and refunds from the gross amount.
Note: Expenses include fees, shipping labels, and donations. Refunds include gross refunds, gross claims, and gross payment disputes.
Note: Only charges and credits tied to the order are shown, and they appear in near real time for orders created within the selected order creation time window.
The response returns earnings information only for the order identified by the order_id path parameter.
Note: Access to the order_earnings resource is currently limited to only US, China, or Hong Kong sellers who meet the following criteria and also request access:
- US sellers with the country of residence set to US and having a payout currency in USD.
- Hong Kong or China sellers having the country of residence set to HK or CN and the payout currency set to USD have access.
To request access, submit an application growth check to have the required OAuth scope added to your app. After submission, you can use the same growth check link to track the status of the request.
eBay plans on expanding this to other markets in the future.
Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
",
+ "operationId": "getOrderEarningsById",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See HTTP request headers for the marketplace ID values.
Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "order_id",
+ "in": "path",
+ "description": "This path parameter identifies the specific order for which earnings information is requested.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/OrderEarning"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "135023": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "Invalid order ID format."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "x-response-codes": {
+ "errors": {
+ "135022": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The order was not found."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "135000": {
+ "domain": "API_FINANCES",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances.earnings.read"
+ ]
+ }
+ ]
}
- },
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "135002": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of payout status filter is invalid."
+ },
+ "/order_earnings_summary": {
+ "get": {
+ "tags": [
+ "order_earnings"
+ ],
+ "description": "This method returns a summarized view of order earnings information for one or more orders associated with a seller account. The method retrieves aggregated data for order earnings after deducting expenses and refunds from the gross amount. You can use this method for high-level financial reporting workflows.
Note: Expenses include fees, shipping labels, and donations. Refunds include gross refunds, gross claims, and gross payment disputes.
Note: Only charges and credits tied to the order are shown, and they appear in near real time for orders created within the selected order creation time window.
The response can be filtered by using the filter parameter. This parameter allows consumers to restrict the summary results returned by the method based on supported filtering criteria.
Note: Access to the order_earnings resource is currently limited to only US, China, or Hong Kong sellers who meet the following criteria and also request access:
- US sellers with the country of residence set to US and having a payout currency in USD.
- Hong Kong or China sellers having the country of residence set to HK or CN and the payout currency set to USD have access.
To request access, submit an application growth check to have the required OAuth scope added to your app. After submission, you can use the same growth check link to track the status of the request.
eBay plans on expanding this to other markets in the future.
Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
",
+ "operationId": "getOrderEarningsSummary",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See HTTP request headers for the marketplace ID values.
Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This parameter can be used to filter orders created within a specified date range. The filter uses the orderCreationDate field, which works similarly to the transactionDate filter used by the Transactions API. Currently, orderCreationDate is the only supported filter value.Note: All dates must be input using UTC format (YYYY-MM-DDTHH:MM:SS.SSSZ) and should be adjusted accordingly for the local timezone of the user.
Default: If no value is specified, results from the past year will be returned.
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:FilterField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/OrderEarningsSummary"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "135019": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The orderCreationDate filter is invalid due to syntax issue, or the start and end dates are not compatible with one another. Please see documentation."
+ },
+ "135020": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied date range is invalid, as orders before year 2024 cannot be retrieved. Please update the date range and resubmit the request."
+ },
+ "135021": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied date range is invalid, as the date range cannot exceed 12 months. Please update the date range and resubmit the request."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "135000": {
+ "domain": "API_FINANCES",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
},
- "135003": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of pagination is invalid."
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances.earnings.read"
+ ]
+ }
+ ]
+ }
+ },
+ "/payout/{payout_Id}": {
+ "get": {
+ "tags": [
+ "payout"
+ ],
+ "description": "Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
This method retrieves details on a specific seller payout. The unique identifier of the payout is passed in as a path parameter at the end of the call URI.
The getPayouts method can be used to retrieve the unique identifier of a payout, or the user can check Seller Hub.
For split-payout cases, which are only available to sellers in mainland China, this method will return the payoutPercentage for the specified payout. This value indicates the current payout percentage allocated to a payment instrument. This method will also return the convertedToCurrency and convertedToValue response fields in CNY value.
Note: In split-payout cases, this method will only return details on an individual payout, also known as a true(actual) payoutid. If a user inputs a payoutReference id as a path parameter, the call will fail and the 404 not found status code will be returned.
For more information on split payouts, see Mainland China Split Payout Playbook.",
+ "operationId": "getPayout",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See HTTP request headers for the marketplace ID values.
Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "payout_Id",
+ "in": "path",
+ "description": "This path parameter is used to specify the unique identifier of the payout being retrieved.
Use the getPayouts method to retrieve payout IDs, or check Seller Hub to get the payout ID. ",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Payout"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request"
+ },
+ "404": {
+ "description": "Not found",
+ "x-response-codes": {
+ "errors": {
+ "135001": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The payout id was not found."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "135000": {
+ "domain": "API_FINANCES",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
},
- "135004": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of payout date filter is invalid."
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances"
+ ]
+ }
+ ]
+ }
+ },
+ "/payout": {
+ "get": {
+ "tags": [
+ "payout"
+ ],
+ "description": "Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
This method is used to retrieve the details of one or more seller payouts. By using the filter query parameter, users can retrieve payouts processed within a specific date range, and/or they can retrieve payouts in a specific state.
There are also pagination and sort query parameters that allow users to control the payouts that are returned in the response.
If no payouts match the input criteria, an empty payload is returned.
For split-payout cases, which are only available to sellers in mainland China, this method will return the payoutPercentage for the specified payout. This value indicates the current payout percentage allocated to a payout instrument. This method will also return the convertedToCurrency and convertedTo response fields set to CNY value and the payoutReference, the unique identifier reference (not true payout).
By using the filter query parameter, users can retrieve the two true(actual) payouts associated with a payoutReference.
Note: For more information on split payouts, see Mainland China Split Payout Playbook.
Note: Only payouts less than 5 years in the past can be retrieved.",
+ "operationId": "getPayouts",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See HTTP request headers for the marketplace ID values.
Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "The filter types that can be used here are discussed below. If none of these filters are used, all payouts in all states from within the last five years are returned:
- payoutDate: search for payouts within a specific range of dates. The date format to use is
YYYY-MM-DDTHH:MM:SS.SSSZ. Below is the proper syntax to use if filtering by a date range:
https://apiz.ebay.com/sell/finances/v1/payout?filter=payoutDate:[2024-12-17T00:00:01.000Z..2024-12-24T00:00:01.000Z]
Only payouts from the last five years can be retrieved, so make sure the starting date is less than five years in the past from the present time. Also, the maximum date range that can be specified through this date filter is 36 months, so make sure your specified date range is no more than 36 months. - lastAttemptedPayoutDate: search for attempted payouts that failed within a specific range of dates. In order to use this filter, the payoutStatus filter must also be used and its value must be set to
RETRYABLE_FAILED. The date format to use is YYYY-MM-DDTHH:MM:SS.SSSZ. The same syntax and requirements applicable to the payoutDate filter also apply to the lastAttemptedPayoutDate filter.
This filter is only applicable (and will return results) if one or more seller payouts have failed, but are retryable. - payoutStatus: search for payouts in a particular state. Only one payout state can be specified with this filter. For supported payoutStatus values, see PayoutStatusEnum.
Below is the proper syntax to use if filtering by payout status:
https://apiz.ebay.com/sell/finances/v1/payout?filter=payoutStatus:{SUCCEEDED} - payoutReference: returns the two true (actual) payouts associated with the payoutReference id. This parameter can support up to 200 payoutReference inputs. This filter is only supported for mainland China sellers. Below is the proper syntax to use if filtering by a specific payoutReference:
https://apiz.ebay.com/sell/finances/v1/payout?filter=payoutReference:{5********3}
If both the payoutDate and payoutStatus filters are used, payouts must satisfy both criteria to be returned. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:FilterField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The number of payouts to return per page of the result set. Use this parameter in conjunction with the offset parameter to control the pagination of the output.
For example, if offset is set to 10 and limit is set to 10, the method retrieves payouts 11 thru 20 from the result set.
Note: This feature employs a zero-based list, where the first payout in the results set has an offset value of 0.
Maximum: 200
Default: 20",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "This integer value indicates the actual position that the first payout returned on the current page has in the results set. So, if you wanted to view the 11th payout of the result set, you would set the offset value in the request to 10.
In the request, you can use the offset parameter in conjunction with the limit parameter to control the pagination of the output. For example, if offset is set to 30 and limit is set to 10, the method retrieves payouts 31 thru 40 from the resulting collection of payouts.
To avoid poor response time, use offset values of less than 5000.
Note: This feature employs a zero-based list, where the first payout in the results set has an offset value of 0.
Default: 0 (zero)",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sort",
+ "in": "query",
+ "description": "By default, payouts or failed payouts that match the input criteria are sorted in descending order according to the payout date/last attempted payout date (i.e., most recent payouts returned first).
To view payouts in ascending order instead (i.e., oldest payouts/attempted payouts first,) you would include the sort query parameter, and then set the value of its field parameter to payoutDate or lastAttemptedPayoutDate (if searching for failed, retryable payouts). Below is the proper syntax to use if filtering by a payout date range in ascending order:
https://apiz.ebay.com/sell/finances/v1/payout?filter=payoutDate:[2018-12-17T00:00:01.000Z..2018-12-24T00:00:01.000Z]&sort=payoutDate
Payouts can only be sorted according to payout date, and can not be sorted by payout status. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:SortField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Payouts"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "135002": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of payout status filter is invalid."
+ },
+ "135003": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of pagination is invalid."
+ },
+ "135004": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of payout date filter is invalid."
+ },
+ "135005": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of sort is invalid."
+ },
+ "135013": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied start date is invalid, as payouts older than five years cannot be retrieved. Please update the start date and resubmit the request."
+ },
+ "135014": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied date range is invalid, as the date range cannot exceed 36 months. Please update the date range and resubmit the request."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "135000": {
+ "domain": "API_FINANCES",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
},
- "135005": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of sorting is invalid."
- }
- }
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances"
+ ]
+ }
+ ]
}
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "135000": {
- "domain": "API_FINANCES",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
+ },
+ "/payout_summary": {
+ "get": {
+ "tags": [
+ "payout"
+ ],
+ "description": "Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
This method is used to retrieve cumulative values for payouts in a particular state, or all states. The metadata in the response includes total payouts, the total number of monetary transactions (sales, refunds, credits) associated with those payouts, and the total dollar value of all payouts.
If the filter query parameter is used to filter by payout status, only one payout status value may be used. If the filter query parameter is not used to filter by a specific payout status, cumulative values for payouts in all states are returned.
The user can also use the filter query parameter to specify a date range, and then only payouts that were processed within that date range are considered.
Note: getPayoutSummary will only return data on payouts that occurred less than five years in the past.",
+ "operationId": "getPayoutSummary",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See HTTP request headers for the marketplace ID values.
Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "The two filter types that can be used here are discussed below. One or both of these filter types can be used. If none of these filters are used, the data returned in the response will reflect all payouts in all states that have occurred within the last five years:
- payoutDate: consider payouts processed within a specific range of dates. The date format to use is
YYYY-MM-DDTHH:MM:SS.SSSZ. Below is the proper syntax to use if filtering by a date range:
https://apiz.ebay.com/sell/finances/v1/payout_summary?filter=payoutDate:[2024-12-17T00:00:01.000Z..2024-12-24T00:00:01.000Z]
Only payouts from the last five years can be retrieved, so make sure the starting date is less than five years in the past from the present time. Also, the maximum date range that can be specified through this date filter is 36 months, so make sure your specified date range is no more than 36 months. - payoutStatus: consider only the payouts in a particular state. Only one payout state can be specified with this filter. For supported payoutStatus values, see PayoutStatusEnum.
Below is the proper syntax to use if filtering by payout status:
https://apiz.ebay.com/sell/finances/v1/payout_summary?filter=payoutStatus:{SUCCEEDED}
If both the payoutDate and payoutStatus filters are used, only the payouts that satisfy both criteria are considered in the results. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:FilterField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PayoutSummaryResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "135002": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of payout status filter is invalid"
+ },
+ "135004": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of payout date filter is invalid"
+ },
+ "135013": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied start date is invalid, as payouts older than five years cannot be retrieved. Please update the start date and resubmit the request."
+ },
+ "135014": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied date range is invalid, as the date range cannot exceed 36 months. Please update the date range and resubmit the request."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "135000": {
+ "domain": "API_FINANCES",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.finances"
- ]
- }
- ]
- }
- },
- "/payout_summary": {
- "get": {
- "tags": [
- "payout"
- ],
- "description": "This method is used to retrieve cumulative values for payouts in a particular state, or all states. The metadata in the response includes total payouts, the total number of monetary transactions (sales, refunds, credits) associated with those payouts, and the total dollar value of all payouts.
If the filter query parameter is used to filter by payout status, only one payout status value may be used. If the filter query parameter is not used to filter by a specific payout status, cumulative values for payouts in all states are returned.
The user can also use the filter query parameter to specify a date range, and then only payouts that were processed within that date range are considered.",
- "operationId": "getPayoutSummary",
- "parameters": [
- {
- "name": "filter",
- "in": "query",
- "description": "The two filter types that can be used here are discussed below. One or both of these filter types can be used. If none of these filters are used, the data returned in the response will reflect payouts, in all states, processed within the last 90 days. - payoutDate: consider payouts processed within a specific range of dates. The date format to use is
YYYY-MM-DDTHH:MM:SS.SSSZ. Below is the proper syntax to use if filtering by a date range:
https://apiz.ebay.com/sell/finances/v1/payout_summary?filter=payoutDate:[2018-12-17T00:00:01.000Z..2018-12-24T00:00:01.000Z]
Alternatively, the user could omit the ending date, and the date range would include the starting date and up to 90 days past that date, or the current date if the starting date is less than 90 days in the past. - payoutStatus: consider only the payouts in a particular state. Only one payout state can be specified with this filter. The supported payoutStatus values are as follows:
INITIATED: search for payouts that have been initiated but not processed.SUCCEEDED: consider only successful payouts.RETRYABLE_FAILED: consider only payouts that failed, but ones which will be tried again.TERMINAL_FAILED: consider only payouts that failed, and ones that will not be tried again.-
REVERSED: consider only payouts that were reversed.
Below is the proper syntax to use if filtering by payout status:
https://apiz.ebay.com/sell/finances/v1/payout_summary?filter=payoutStatus:{SUCCEEDED}
If both the payoutDate and payoutStatus filters are used, only the payouts that satisfy both criteria are considered in the results. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:FilterField",
- "required": false,
- "schema": {
- "type": "string"
+ "/seller_funds_summary": {
+ "get": {
+ "tags": [
+ "seller_funds_summary"
+ ],
+ "description": "Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
This method retrieves all pending funds that have not yet been distributed through a seller payout.
There are no input parameters for this method. The response payload includes available funds, funds being processed, funds on hold, and also an aggregate count of all three of these categories.
If there are no funds that are pending, on hold, or being processed for the seller's account, no response payload is returned, and an http status code of 204 - No Content is returned instead.",
+ "operationId": "getSellerFundsSummary",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See HTTP request headers for the marketplace ID values.
Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SellerFundsSummaryResponse"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "135000": {
+ "domain": "API_FINANCES",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances"
+ ]
+ }
+ ]
}
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/PayoutSummaryResponse"
- }
- }
+ },
+ "/transaction": {
+ "get": {
+ "tags": [
+ "transaction"
+ ],
+ "description": "Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
The getTransactions method allows a seller to retrieve information about one or more of their monetary transactions.
Note: For a complete list of transaction types, refer to TransactionTypeEnum.
Numerous input filters are available which can be used individually or combined to refine the data that are returned. For example:SALE transactions for August 15, 2022;RETURN transactions for the month of January, 2021;- Transactions currently in a
transactionStatus equal to FUNDS_ON_HOLD.
Refer to the filter field for additional information about each filter and its use.
Pagination and sort query parameters are also provided that allow users to further control how monetary transactions are displayed in the response.
If no monetary transactions match the input criteria, an http status code of 204 No Content is returned with no response payload.
Note: Only monetary transactions that have occurred within the last five years can be retrieved.",
+ "operationId": "getTransactions",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See HTTP request headers for the marketplace ID values.
Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "Numerous filters are available for the getTransactions method, and these filters are discussed below. One or more of these filter types can be used. If none of these filters are used, all monetary transactions occurring within the last five years are returned:- transactionDate: search for monetary transactions that occurred within a specific range of dates.
Note: All dates must be input using UTC format (YYYY-MM-DDTHH:MM:SS.SSSZ) and should be adjusted accordingly for the local timezone of the user.
Below is the proper syntax to use if filtering by a date range:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionDate:[2024-10-23T00:00:01.000Z..2024-11-09T00:00:01.000Z]
Only payouts from the last five years can be retrieved, so make sure the starting date is less than five years in the past from the present time. Also, the maximum date range that can be specified through this date filter is 36 months, so make sure your specified date range is no more than 36 months. - transactionType: search for a specific type of monetary transaction. For supported transactionType values, see TransactionTypeEnum.
Below is the proper syntax to use if filtering by a monetary transaction type:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionType:{SALE} - transactionStatus: this filter type is only applicable for sales orders, and allows the user to filter seller payouts in a particular state. For supported transactionStatus values, see TransactionStatusEnum.
Below is the proper syntax to use if filtering by transaction status:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionStatus:{PAYOUT} - buyerUsername: the eBay username or user ID of the buyer involved in the monetary transaction. Only monetary transactions involving this buyer are returned. Below is the proper syntax to use if filtering by a specific eBay buyer:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=buyerUsername:{buyer1234} - payoutId: the unique identifier of a seller payout. This value is auto-generated by eBay once the seller payout is set to be processed. Only monetary transactions involving this Payout ID are returned. Below is the proper syntax to use if filtering by a specific Payout ID:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=payoutId:{5********8} - transactionId: use this field transactionId and also transactionType to filter for a unique identifier of a monetary transaction, or an error will occur. For a sales order, the orderId filter should be used instead. Only the monetary transaction defined by the identifier is returned.
Note: This filter cannot be used alone; the transactionType must also be specified when filtering by transaction ID.
Below is the proper syntax to use if filtering by a specific transaction ID:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionId:{0*-0***0-3***3}&filter=transactionType:{SALE} - orderId: the unique identifier of a sales order. Only monetary transaction(s) associated with this orderId value are returned.
For any other monetary transaction, the transactionId filter should be used instead.
Below is the proper syntax to use if filtering by a specific order ID:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=orderId:{0*-0***0-3***3} - payoutReference: returns the monetary transactions associated with the payoutReference. By using this ID as a filter parameter, the user will be able to track all monetary transactions associated with both sibling payouts, including sales and refunds, if any. This filter is only supported for sellers in Mainland China. Below is the proper syntax to use if filtering by payoutReference:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=payoutReference:{5*******3}
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:FilterField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The number of monetary transactions to return per page of the result set. Use this parameter in conjunction with the offset parameter to control the pagination of the output.
For example, if offset is set to 10 and limit is set to 10, the method retrieves monetary transactions 11 thru 20 from the result set.
Note: This feature employs a zero-based list, where the first item in the list has an offset of 0.
Maximum: 1000
Default: 20",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "This integer value indicates the actual position that the first monetary transaction returned on the current page has in the results set. So, if you wanted to view the 11th monetary transaction of the result set, you would set the offset value in the request to 10.
In the request, you can use the offset parameter in conjunction with the limit parameter to control the pagination of the output. For example, if offset is set to 30 and limit is set to 10, the method retrieves transactions 31 thru 40 from the resulting collection of transactions.
To avoid poor response time, use offset values of less than 5000.
Note: This feature employs a zero-based list, where the first item in the list has an offset of 0.
Default: 0 (zero)",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sort",
+ "in": "query",
+ "description": "By default, monetary transactions that match the input criteria are sorted in descending order according to the transaction date (i.e, most recent transactions returned first).
To view transactions in ascending order instead (i.e., oldest transactions first), you would include the sort query parameter and set its value to transactionDate. Below is the proper syntax to use if filtering by a transaction date range in ascending order:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionDate:[2023-10-01T00:00:01.000Z..2023-10-12T00:00:01.000Z]&sort=transactionDate
Transactions can only be sorted according to transaction date. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:SortField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Transactions"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "135003": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of pagination is invalid."
+ },
+ "135005": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of sort is invalid."
+ },
+ "135006": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of transaction type filter is invalid."
+ },
+ "135007": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of transaction status filter is invalid."
+ },
+ "135008": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of transaction date filter is invalid."
+ },
+ "135009": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "Transaction type filter is missing."
+ },
+ "135015": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied start date is invalid, as transactions older than five years cannot be retrieved. Please update the start date and resubmit the request."
+ },
+ "135016": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied date range is invalid, as the date range cannot exceed 36 months. Please update the date range and resubmit the request."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "135000": {
+ "domain": "API_FINANCES",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances"
+ ]
+ }
+ ]
}
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "135002": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of payout status filter is invalid"
+ },
+ "/transaction_summary": {
+ "get": {
+ "tags": [
+ "transaction"
+ ],
+ "description": "Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
The getTransactionSummary method retrieves cumulative information for monetary transactions. If applicable, the number of payments with a transactionStatus equal to FUNDS_ON_HOLD and the total monetary amount of these on-hold payments are also returned.
Note: For a complete list of transaction types, refer to TransactionTypeEnum.
Refer to the filter field for additional information about each filter and its use.
Note: Unless a transactionType filter is used to retrieve a specific type of transaction (e.g., SALE, REFUND, etc.,) the creditCount and creditAmount response fields both include order sales and seller credits information. That is, the count and value fields do not distinguish between these two types monetary transactions.
Note: getTransactionSummary will only return data on transactions that occurred less than five years in the past.",
+ "operationId": "getTransactionSummary",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See HTTP request headers for the marketplace ID values.
Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "Numerous filters are available for the getTransactionSummary method, and these filters are discussed below. One or more of these filter types can be used. The transactionStatus filter must be used. All other filters are optional. - transactionStatus: the data returned in the response pertains to the sales, payouts, and transfer status set. For supported transactionStatus values, see TransactionStatusEnum.
Below is the proper syntax to use when setting up the transactionStatus filter:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionStatus:{PAYOUT} - transactionDate: only consider monetary transactions that occurred within a specific range of dates.
Note: All dates must be input using UTC format (YYYY-MM-DDTHH:MM:SS.SSSZ) and should be adjusted accordingly for the local timezone of the user.
Below is the proper syntax to use if filtering by a date range:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionDate:[2024-10-23T00:00:01.000Z..2024-11-09T00:00:01.000Z]
Note:Only monetary transactions from the last five years can be retrieved, so make sure the starting date is less than five years in the past from the present time. Also, the maximum date range that can be specified through this date filter is 36 months, so make sure your specified date range is no more than 36 months. - transactionType: only consider a specific type of monetary transaction. For supported transactionType values, see TransactionTypeEnum.
Below is the proper syntax to use if filtering by a monetary transaction type:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionType:{SALE} - buyerUsername: only consider monetary transactions involving a specific buyer (specified with the buyer's eBay username or user ID). Below is the proper syntax to use if filtering by a specific eBay buyer:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=buyerUsername:{buyer1234} - payoutId: only consider monetary transactions related to a specific seller payout (identified with a Payout ID). This value is auto-generated by eBay once the seller payout is set to be processed. Below is the proper syntax to use if filtering by a specific Payout ID:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=payoutId:{5********8} - transactionId: the unique identifier of a monetary transaction. For a sales order, the orderId filter should be used instead. Only the monetary transaction(s) associated with this transactionId value are returned.
Note: This filter cannot be used alone; the transactionType must also be specified when filtering by transaction ID.
Below is the proper syntax to use if filtering by a specific transaction ID:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionId:{0*-0***0-3***3}&filter=transactionType:{SALE} - orderId: the unique identifier of a sales order. For any other monetary transaction, the transactionId filter should be used instead. Only the monetary transaction(s) associated with this orderId value are returned. Below is the proper syntax to use if filtering by a specific order ID:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=orderId:{0*-0***0-3***3}
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:FilterField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/TransactionSummaryResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "135006": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of transaction type filter is invalid."
+ },
+ "135007": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of transaction status filter is invalid."
+ },
+ "135008": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The value of transaction date filter is invalid."
+ },
+ "135009": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "Transaction type filter is missing."
+ },
+ "135011": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "Transaction status filter is mandatory."
+ },
+ "135015": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied start date is invalid, as transactions older than five years cannot be retrieved. Please update the start date and resubmit the request."
+ },
+ "135016": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The supplied date range is invalid, as the date range cannot exceed 36 months. Please update the date range and resubmit the request."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "135000": {
+ "domain": "API_FINANCES",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
},
- "135004": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of payout date filter is invalid"
- }
- }
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances"
+ ]
+ }
+ ]
}
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "135000": {
- "domain": "API_FINANCES",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
+ },
+ "/transfer/{transfer_Id}": {
+ "get": {
+ "tags": [
+ "transfer"
+ ],
+ "description": "Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
This method retrieves detailed information regarding a TRANSFER transaction type. A TRANSFER is a monetary transaction type that involves a seller transferring money to eBay for reimbursement of one or more charges. For example, when a seller reimburses eBay for a buyer refund.
If an ID is passed into the URI that is an identifier for another transaction type, this call will return an http status code of 404 Not found.",
+ "operationId": "getTransfer",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See HTTP request headers for the marketplace ID values.
Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "transfer_Id",
+ "in": "path",
+ "description": "This path parameter is used to specify the unique identifier of the TRANSFER transaction type you wish to retrieve.
Use the getTransactions method to retrieve this value by setting the transactionType filter to TRANSFER. The transfer_id value will then be returned in the transaction_id field of the response.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Transfer"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request"
+ },
+ "404": {
+ "description": "Not found.",
+ "x-response-codes": {
+ "errors": {
+ "135012": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The transfer id was not found."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error.",
+ "x-response-codes": {
+ "errors": {
+ "135000": {
+ "domain": "API_FINANCES",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.finances"
+ "/billing_activity": {
+ "get": {
+ "tags": [
+ "billing_activity"
+ ],
+ "description": "Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
This method retrieves filtered billing activities of the seller. Returned results are filtered through query parameters such as date range, activity ID, listing ID, or order ID. Sorting and pagination features help organize and navigate returned activities efficiently.",
+ "operationId": "getBillingActivities",
+ "parameters": [
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header indicates the natural language and locale preferred by the user for the response.
For more information, see the Accept-Language header in HTTP request headers and Marketplace ID values. If not provided, defaults to en-US.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This required field specifies which results to return in the response. Only one of the following four filter values must be used. A user can either retrieve all billing activity within a date range, or they can retrieve billing activity related to a specific eBay order, eBay listing, or they can retrieve information on a specific billing activity.
- activityId: If this filter is used, only information on a specific billing activity is returned. The billingTransactionId returned in the response can be used as the activityId.
- listingId: If this filter is used, only billing activity associated with the specified listing is returned.
- orderId: If this filter is used, only billing activity associated with the specified order is returned.
- transactionDate: If a date range filter is used, only billing activity that occurred within the specified date range is returned. The starting date cannot be set back further than 120 days in the past. Use UTC date values in the following order:
[start..end]
Examples
IDs:
filter=activityID:{12**56}
Date range:
filter=transactionDate:[2025-10-01T00:00:00Z..2025-10-31T23:59:59Z] For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:FilterField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "Sets the maximum number of records to return per page of data.
Use this parameter in conjunction with the offset parameter to control the pagination of the output. For example, with offset set to 20 and limit set to 10, the call retrieves entries 21 through 30 from the result set.
Although this field is optional, if omitted the default value of 100 is used.
Minimum: 1
Maximum: 200
Default: 100",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "Specifies the number of records to skip in the result set. This is used with the limit field to control the pagination of the output. For example:
- If offset is
0 and limit is 10, the method will retrieve records 1-10 from the list of records returned - If offset is
10 and limit is 10, the method will retrieve records 11-20 from the list of records returned.
If this parameter is not set, its value defaults to 0 which returns the first page of records.
Note: This feature employs a zero-based list, where the first activity in the list has an offset of 0.
Default: 0 (zero, returns the first page)
",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sort",
+ "in": "query",
+ "description": "By default, transactions that match the input criteria are sorted in descending order according to the transaction date (most recent transactions returned first).
To view transactions in ascending order instead (oldest transactions first), include the sort query parameter and set its value to sort=transactionDate. For example (ascending order):
filter=transactionDate:[2025-11-01T00:00:01.000Z..2025-11-12T00:00:01.000Z]&sort=transactionDate
Transactions can only be sorted according to transaction date. If omitted, defaults to descending order (most recent transactions returned first). For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:SortField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BillingActivityResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "135005": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The sort value is invalid. See documentation for supported values."
+ },
+ "135015": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "At least one filter parameter must be used. See documentation for supported filter types."
+ },
+ "135016": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "Invalid filter format. See documentation for correct format for each filter type."
+ },
+ "135017": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "Invalid filter type. See documentation for supported filter types."
+ },
+ "135018": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "Only one filter type can be used at a time."
+ },
+ "135019": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "Invalid date format. Date must be in ISO-8601 format (e.g., 2024-10-23T00:00:01.000Z)."
+ },
+ "135020": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "There is a syntax error in your date_range filter. Please see documentation for proper syntax."
+ },
+ "135021": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "The starting date range cannot be set back further than 120 days in the past."
+ },
+ "135022": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "Invalid limit value. Limit must be between 1 and 200."
+ },
+ "135023": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "Invalid offset value. If provided, Offset must be 0 or greater."
+ },
+ "135025": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "Invalid date range: the end date occurs before the start date."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "135000": {
+ "domain": "API_FINANCES",
+ "category": "REQUEST",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances"
+ ]
+ }
+ ]
+ },
+ "servers": [
+ {
+ "url": "https://api.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/finances/v1"
+ }
+ }
+ }
]
- }
- ]
- }
+ }
},
- "/transaction": {
- "get": {
- "tags": [
- "transaction"
- ],
- "description": "This method allows a seller to retrieve one or monetary transactions. In this case, 'monetary transactions' include sales orders, buyer refunds, seller credits, buyer-initiated payment disputes, eBay shipping label purchases, and transfers. There are numerous input filters available for use, including filters to retrieve specific types of monetary transactions, to retrieve monetary transactions processed within a specific date range, or to retrieve monetary transactions in a specific state. See the filter field for more information on each filter, and how each one is used.
There are also pagination and sort query parameters that allow users to further control the monetary transactions that are returned in the response.
If no monetary transactions match the input criteria, an http status code of 204 No Content is returned with no response payload.",
- "operationId": "getTransactions",
- "parameters": [
- {
- "name": "filter",
- "in": "query",
- "description": "Numerous filters are available for the getTransactions method, and these filters are discussed below. One or more of these filter types can be used. If none of these filters are used, all monetary transactions from the last 90 days are returned:- transactionDate: search for monetary transactions that occurred within a specific range of dates.
Note: All dates must be input using UTC format (YYYY-MM-DDTHH:MM:SS.SSSZ) and should be adjusted accordingly for the local timezone of the user.
Below is the proper syntax to use if filtering by a date range:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionDate:[2018-10-23T00:00:01.000Z..2018-11-09T00:00:01.000Z]
Alternatively, the user could omit the ending date, and the date range would include the starting date and up to 90 days past that date, or the current date if the starting date is less than 90 days in the past. - transactionType: search for a specific type of monetary transaction. The supported transactionType values are as follows:
SALE: a sales order.-
REFUND: a refund to the buyer after an order cancellation or return. CREDIT: a credit issued by eBay to the seller's account.DISPUTE: a monetary transaction associated with a payment dispute between buyer and seller.NON_SALE_CHARGE: a monetary transaction involving a seller transferring money to eBay for the balance of a charge for NON_SALE_CHARGE transactions (transactions that contain non-transactional seller fees). These can include a one-time payment, monthly/yearly subscription fees charged monthly, NRC charges, and fee credits.SHIPPING_LABEL: a monetary transaction where eBay is billing the seller for an eBay shipping label. Note that the shipping label functionality will initially only be available to a select number of sellers.TRANSFER: A transfer is a monetary transaction where eBay is billing the seller for reimbursement of a charge. An example of a transfer is a seller reimbursing eBay for a buyer refund.
Below is the proper syntax to use if filtering by a monetary transaction type:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionType:{SALE} - transactionStatus: this filter type is only applicable for sales orders, and allows the user to filter seller payouts in a particular state. The supported transactionStatus values are as follows:
PAYOUT: this indicates that the proceeds from the corresponding sales order has been paid out to the seller's account.FUNDS_PROCESSING: this indicates that the funds for the corresponding monetary transaction are currently being processed.FUNDS_AVAILABLE_FOR_PAYOUT: this indicates that the proceeds from the corresponding sales order are available for a seller payout, but processing has not yet begun.FUNDS_ON_HOLD: this indicates that the proceeds from the corresponding sales order are currently being held by eBay, and are not yet available for a seller payout.COMPLETED: this indicates that the funds for the corresponding TRANSFER monetary transaction have transferred and the transaction has completed.FAILED: this indicates the process has failed for the corresponding TRANSFER monetary transaction.
Below is the proper syntax to use if filtering by transaction status:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionStatus:{PAYOUT} - buyerUsername: the eBay user ID of the buyer involved in the monetary transaction. Only monetary transactions involving this buyer are returned. Below is the proper syntax to use if filtering by a specific eBay buyer:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=buyerUsername:{buyer1234} - salesRecordReference: the unique Selling Manager identifier of the order involved in the monetary transaction. Only monetary transactions involving this Selling Manager Sales Record ID are returned. Below is the proper syntax to use if filtering by a specific Selling Manager Sales Record ID:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=salesRecordReference:{123}
Note: For all orders originating after February 1, 2020, a value of 0 will be returned in the salesRecordReference field. So, this filter will only be useful to retrieve orders than occurred before this date. - payoutId: the unique identifier of a seller payout. This value is auto-generated by eBay once the seller payout is set to be processed. Only monetary transactions involving this Payout ID are returned. Below is the proper syntax to use if filtering by a specific Payout ID:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=payoutId:{5000106638} - transactionId: the unique identifier of a monetary transaction. For a sales order, the orderId filter should be used instead. Only the monetary transaction defined by the identifier is returned.
Note: This filter cannot be used alone; the transactionType must also be specified when filtering by transaction ID.
Below is the proper syntax to use if filtering by a specific transaction ID:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionId:{03-03620-33763}&filter=transactionType:{SALE} - orderId: the unique identifier of a sales order. For any other monetary transaction, the transactionId filter should be used instead. Only the sales order defined by the identifier is returned. Below is the proper syntax to use if filtering by a specific order ID:
https://apiz.ebay.com/sell/finances/v1/transaction?filter=orderId:{03-03620-33763}
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:FilterField",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "sort",
- "in": "query",
- "description": "Sorting is not yet available for the getTransactions method. By default, monetary transactions that match the input criteria are sorted in descending order according to the transaction date. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:SortField",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "limit",
- "in": "query",
- "description": "The number of monetary transactions to return per page of the result set. Use this parameter in conjunction with the offset parameter to control the pagination of the output.
For example, if offset is set to 10 and limit is set to 10, the method retrieves monetary transactions 11 thru 20 from the result set.
Note: This feature employs a zero-based list, where the first item in the list has an offset of 0. If an orderId, transactionId, or payoutId filter is included in the request, any limit value will be ignored.
Maximum: 1000
Default: 20",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "This integer value indicates the actual position that the first monetary transaction returned on the current page has in the results set. So, if you wanted to view the 11th monetary transaction of the result set, you would set the offset value in the request to 10.
In the request, you can use the offset parameter in conjunction with the limit parameter to control the pagination of the output. For example, if offset is set to 30 and limit is set to 10, the method retrieves transactions 31 thru 40 from the resulting collection of transactions.
Note: This feature employs a zero-based list, where the first item in the list has an offset of 0.
Default: 0 (zero)",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Transactions"
- }
- }
- }
- },
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "135003": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of pagination is invalid."
+ "components": {
+ "schemas": {
+ "Amount": {
+ "type": "object",
+ "properties": {
+ "convertedFromCurrency": {
+ "type": "string",
+ "description": "The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency.
This field is only returned if/when currency conversion was applied by eBay. For implementation help, refer to eBay API documentation"
+ },
+ "convertedFromValue": {
+ "type": "string",
+ "description": "The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field.
This field is only returned if/when currency conversion was applied by eBay."
+ },
+ "convertedToCurrency": {
+ "type": "string",
+ "description": "Note: This field is only applicable for Mainland China sellers with an available CNY Bank payment instrument. This response can only have a value of CNY.The three-letter ISO 4217 code representing the currency of the amount in the convertedToValue field.
This field is only returned for payouts to bank accounts when currency conversion was applied by eBay. For implementation help, refer to eBay API documentation"
+ },
+ "convertedToValue": {
+ "type": "string",
+ "description": "Note: This field is only applicable for Mainland China sellers with an available CNY Bank payment instrument. This response only returns value in CNY.The monetary value after any conversion is performed, in the currency specified by the convertedToCurrency field. This value is the converted amount.
The field is only returned for payouts to bank accounts when currency conversion was applied by eBay."
+ },
+ "currency": {
+ "type": "string",
+ "description": "A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type.
Default: The currency of the authenticated user's country. For implementation help, refer to eBay API documentation"
+ },
+ "exchangeRate": {
+ "type": "string",
+ "description": "The exchange rate used for the monetary conversion. This field shows the exchange rate used to convert the dollar value in the value field from the dollar value in the convertedFromValue field.
For sellers in mainland China, this field shows the exchange rate to convert the dollar value in the value field to the CNY value in the convertedToValue field.
This field is only returned when eBay does a currency version, and a currency conversion is generally needed if the buyer is viewing, or has purchased an item on an international site.
This field is only returned if/when currency conversion was applied by eBay."
+ },
+ "value": {
+ "type": "string",
+ "description": "The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type."
+ }
},
- "135005": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of sorting is invalid."
+ "description": "This type is used to express the dollar value and currency used for any transaction retrieved with the Finances API, including an order total, a seller payout, a buyer refund, or a seller credit."
+ },
+ "BalanceAdjustment": {
+ "type": "object",
+ "properties": {
+ "adjustmentAmount": {
+ "description": "The seller payout balance amount that will be applied toward the charges outlined in the charges array.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "adjustmentType": {
+ "type": "string",
+ "description": "The enumeration value returned here indicates if the charge is a DEBIT or a CREDIT to the seller. Generally, all transfer transaction types are going to be DEBIT, since the money is being tranferred from the seller to eBay. For implementation help, refer to eBay API documentation"
+ }
},
- "135006": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of transaction type filter is invalid."
+ "description": "This type is used by the balanceAdjustment container, which shows the seller payout balance that will be applied toward the charges outlined in the charges array."
+ },
+ "BillingActivityLineItem": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "This container shows the amount of the fee or credit. The value and currency are always returned. If the buyer is in one country and purchases from an eBay marketplace that uses a different currency, the response also includes the converted-from and converted-to fields, along with the exchange rate.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "billingTransactionDate": {
+ "type": "string",
+ "description": "This timestamp indicates the date/time when eBay processed the transaction."
+ },
+ "billingTransactionId": {
+ "type": "string",
+ "description": "This field provides a unique identifier of the billing transaction. If a seller wants to view details on a specific billing transaction, they can use the actvityId filter and pass in a specific billingTransactionId value."
+ },
+ "bookingEntry": {
+ "type": "string",
+ "description": "The value returned in this field will indicate if the billing transaction is a debit against the seller's account, or a credit. A debit is much more prevalent than a credit, but sometimes a listing fee will get reversed and they will get a credit for this fee. Possible values:
"
+ },
+ "feeType": {
+ "type": "string",
+ "description": "This field describes the type of fee associated with the transaction. An example value is FinalValueFeeFixedFeePerOrder."
+ },
+ "feeTypeDescription": {
+ "type": "string",
+ "description": "This field contains the human-readable description of the fee type associated with the transaction. For example, Final Value Fee."
+ },
+ "listingId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay listing associated with the billing transaction. This field is returned if the fee is associated with a listing."
+ },
+ "orderId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay order associated with the billing transaction. This field is returned if the fee is associated with an order."
+ },
+ "promotionalOffers": {
+ "type": "array",
+ "description": "A list of seller promotional offers applicable for the billing transaction.",
+ "items": {
+ "$ref": "#/components/schemas/DiscountDetail"
+ }
+ }
},
- "135007": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of transaction status filter is invalid."
+ "description": "BillingActivityLineItem"
+ },
+ "BillingActivityResponse": {
+ "type": "object",
+ "properties": {
+ "billingActivities": {
+ "type": "array",
+ "description": "A list of billing activity entries that meet the filter criteria. Billing activity will include fees, credits, and promotional offers applied to the seller's account.",
+ "items": {
+ "$ref": "#/components/schemas/BillingActivityLineItem"
+ }
+ },
+ "count": {
+ "type": "integer",
+ "description": "An integer representing the number of billing activity items returned in this response page.",
+ "format": "int32"
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The value of the limit parameter. This is the maximum number of line items, as filtered, of billing transactions to return per page from the result set.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The URI for the next page of results starting with the resource name. This URI is returned if there is an additional page of results in the result set."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The value of the offset parameter. This field indicates how many results were skipped in the response. If an offset parameter was not included in the request, this value will default to 0, returning the first page of results.",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The URI for the previous page of results starting with the resource name. This URI is returned if there is a previous page of results in the result set."
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of billing transactions available that match the filter criteria. Note: When the total value exceeds the limit value, there are multiple pages of results.
",
+ "format": "int32"
+ }
},
- "135008": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of transaction date filter is invalid."
+ "description": "BillingActivityResponse"
+ },
+ "Buyer": {
+ "type": "object",
+ "properties": {
+ "username": {
+ "type": "string",
+ "description": "The eBay user ID of the order's buyer.
Note: Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to Data Handling Compliance. "
+ }
},
- "135009": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "Transaction type filter is missing."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "135000": {
- "domain": "API_FINANCES",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.finances"
- ]
- }
- ]
- }
- },
- "/transaction_summary": {
- "get": {
- "tags": [
- "transaction"
- ],
- "description": "This method is used to retrieve cumulative values for five types of monetary transactions (order sales, seller credits, buyer refunds, buyer-initiated payment disputes, eBay shipping label purchases, and transfers). If applicable, the number of payment holds and the amount of the holds are also returned.
See the description for the filter query parameter for more information on the available filters.
Note: Unless the transactionType filter is used to retrieve a specific type of monetary transaction (sale, buyer refund, seller credit, payment dispute, shipping label, transfer), the creditCount and creditAmount response fields account for both order sales and seller credits (the count and value is not distinguished between the two monetary transaction types).",
- "operationId": "getTransactionSummary",
- "parameters": [
- {
- "name": "filter",
- "in": "query",
- "description": "Numerous filters are available for the getTransactionSummary method, and these filters are discussed below. One or more of these filter types can be used. The transactionStatus filter must be used. All other filters are optional. - transactionStatus: the data returned in the response pertains to the sales, payouts, and transfer status set. The supported transactionStatus values are as follows:
PAYOUT: only consider monetary transactions where the proceeds from the sales order(s) have been paid out to the seller's bank account.FUNDS_PROCESSING: only consider monetary transactions where the proceeds from the sales order(s) are currently being processed.FUNDS_AVAILABLE_FOR_PAYOUT: only consider monetary transactions where the proceeds from the sales order(s) are available for a seller payout, but processing has not yet begun.FUNDS_ON_HOLD: only consider monetary transactions where the proceeds from the sales order(s) are currently being held by eBay, and are not yet available for a seller payout.COMPLETED: this indicates that the funds for the corresponding TRANSFER monetary transaction have transferred and the transaction has completed.FAILED: this indicates the process has failed for the corresponding TRANSFER monetary transaction.
Below is the proper syntax to use when setting up the transactionStatus filter:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionStatus:{PAYOUT} - transactionDate: only consider monetary transactions that occurred within a specific range of dates.
Note: All dates must be input using UTC format (YYYY-MM-DDTHH:MM:SS.SSSZ) and should be adjusted accordingly for the local timezone of the user.
Below is the proper syntax to use if filtering by a date range:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionDate:[2018-10-23T00:00:01.000Z..2018-11-09T00:00:01.000Z]
Alternatively, the user could omit the ending date, and the date range would include the starting date and up to 90 days past that date, or the current date if the starting date is less than 90 days in the past. - transactionType: only consider a specific type of monetary transaction. The supported transactionType values are as follows:
SALE: a sales order.-
REFUND: a refund to the buyer after an order cancellation or return. CREDIT: a credit issued by eBay to the seller's account.DISPUTE: a monetary transaction associated with a payment dispute between buyer and seller.NON_SALE_CHARGE: a monetary transaction involving a seller transferring money to eBay for the balance of a charge for NON_SALE_CHARGE transactions (transactions that contain non-transactional seller fees). These can include a one-time payment, monthly/yearly subscription fees charged monthly, NRC charges, and fee credits.SHIPPING_LABEL: a monetary transaction where eBay is billing the seller for an eBay shipping label. Note that the shipping label functionality will initially only be available to a select number of sellers.TRANSFER: A transfer is a monetary transaction where eBay is billing the seller for reimbursement of a charge. An example of a transfer is a seller reimbursing eBay for a buyer refund.
Below is the proper syntax to use if filtering by a monetary transaction type:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionType:{SALE} - buyerUsername: only consider monetary transactions involving a specific buyer (specified with the buyer's eBay user ID). Below is the proper syntax to use if filtering by a specific eBay buyer:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=buyerUsername:{buyer1234} - salesRecordReference: only consider monetary transactions corresponding to a specific order (identified with a Selling Manager order identifier). Below is the proper syntax to use if filtering by a specific Selling Manager Sales Record ID:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=salesRecordReference:{123}
Note: For all orders originating after February 1, 2020, a value of 0 will be returned in the salesRecordReference field. So, this filter will only be useful to retrieve orders than occurred before this date. - payoutId: only consider monetary transactions related to a specific seller payout (identified with a Payout ID). This value is auto-generated by eBay once the seller payout is set to be processed. Below is the proper syntax to use if filtering by a specific Payout ID:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=payoutId:{5000106638} - transactionId: the unique identifier of a monetary transaction. For a sales order, the orderId filter should be used instead. Only the monetary transaction(s) associated with this transactionId value are returned.
Note: This filter cannot be used alone; the transactionType must also be specified when filtering by transaction ID.
Below is the proper syntax to use if filtering by a specific transaction ID:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionId:{03-03620-33763}&filter=transactionType:{SALE} - orderId: the unique identifier of a sales order. For any other monetary transaction, the transactionId filter should be used instead. Only the monetary transaction(s) associated with this orderId value are returned. Below is the proper syntax to use if filtering by a specific order ID:
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=orderId:{03-03620-33763}
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/finances/types/cos:FilterField",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/TransactionSummaryResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "135006": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of transaction type filter is invalid."
+ "description": "This type is used to express details about the buyer associated with an order. At this time, the only field in this type is the eBay user ID of the buyer, but more fields may get added at a later date."
+ },
+ "BuyerWithId": {
+ "type": "object",
+ "properties": {
+ "userId": {
+ "type": "string",
+ "description": "The public user id of the buyer"
+ },
+ "username": {
+ "type": "string",
+ "description": "The username of the buyer.
Note: Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to Data Handling Compliance. "
+ }
},
- "135007": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of transaction status filter is invalid."
+ "description": "This type defines identifying information about the buyer associated with an order."
+ },
+ "Charge": {
+ "type": "object",
+ "properties": {
+ "cancellationId": {
+ "type": "string",
+ "description": "The unique identifier of an order cancellation. This field is only applicable and returned if the charge is related to an order cancellation."
+ },
+ "caseId": {
+ "type": "string",
+ "description": "The unique identifier of a case filed against an order. This field is only applicable and returned if the charge is related to a case filed against an order."
+ },
+ "chargeNetAmount": {
+ "description": "This container shows the net amount of the charge, which is the total amount of the charge minus the total amount of fees credited towards this refund as per eBay policy. It is possible for there to be multiple charges from multiple orders with one transfer. The net aggregate amount for all charges found in the charges array can be found in the transferDetail.totalChargeNetAmount container.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "inquiryId": {
+ "type": "string",
+ "description": "The unique identifier of an Item Not Received (INR) inquiry filed against an order. This field is only applicable and returned if the charge is related to has an INR inquiry filed against the order."
+ },
+ "orderId": {
+ "type": "string",
+ "description": "The unique identifier of the order that is associated with the charge."
+ },
+ "paymentDisputeId": {
+ "type": "string",
+ "description": "The unique identifier of a third-party payment dispute filed against an order. This occurs when the buyer files a dispute against the order with their payment provider, and then the dispute comes into eBay's system. This field is only applicable and returned if the charge is related to a third-party payment dispute filed against an order."
+ },
+ "refundId": {
+ "type": "string",
+ "description": "The unique identifier of a buyer refund associated with the charge."
+ },
+ "returnId": {
+ "type": "string",
+ "description": "The unique identifier of an order return. This field is only applicable and returned if the charge is related to an order that was returned by the buyer."
+ }
},
- "135008": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The value of transaction date filter is invalid."
+ "description": "This type is used by the charge container, which is an array of one or more charges related to the transfer."
+ },
+ "DiscountDetail": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "This container shows the amount of the promotion. The value and currency are always returned. If the buyer is in one country and purchases from an eBay marketplace that uses a different currency, the response also includes the converted-from and converted-to fields, and the exchange rate.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "offerType": {
+ "type": "string",
+ "description": "The type of promotional discount applied through the activity's promotional offer amount. Examples include offer types such as ETRS (eBay Top Rated Seller) and PROMOTION."
+ }
},
- "135009": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "Transaction type filter is missing."
+ "description": "This container shows the amount of the promotional offer."
+ },
+ "EarningsSummary": {
+ "type": "object",
+ "properties": {
+ "expenses": {
+ "description": "This container provides the total expenses associated with an order, including:
- Fees and fee credits (transaction fees, other fees, and ad fees)
- Shipping labels
- Donations
It is used by both the getOrderEarnings and getOrderEarningsById methods. Note: Expenses are always in the seller's payout currency. Conversion-related fields (such as exchangeRate or converted from/to fields) in this container do not apply to the order_earnings resource.
",
+ "$ref": "#/components/schemas/Expense"
+ },
+ "grossAmount": {
+ "description": "This container shows the gross amount before any eBay deductions. This amount includes the item subtotal, buyer-paid shipping and handling, and seller-collected tax paid by the buyer.
Note: This amount does not include any taxes or fees that eBay collects from the buyer.
Note: Gross amount is always in the seller's payout currency. Conversion-related fields (such as exchangeRate or converted from/to fields) in this container do not apply to the order_earnings resource.
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "orderEarnings": {
+ "description": "This container shows your earnings after deducting expenses and any refunds from your gross amount.Note: Order earnings are always in the seller's payout currency. Conversion-related fields (such as exchangeRate or converted from/to fields) in this container do not apply to the order_earnings resource.
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "refunds": {
+ "description": "This container includes refunds for returns, cases, cancellations, requests, and disputes. It does not include fee credits.
Note: Refunds are always in the seller's payout currency. Conversion-related fields (such as exchangeRate or converted from/to fields) in this container do not apply to the order_earnings resource.
",
+ "$ref": "#/components/schemas/Amount"
+ }
},
- "135011": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "Transaction status filter is mandatory."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "135000": {
- "domain": "API_FINANCES",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.finances"
- ]
- }
- ]
- }
- },
- "/transfer/{transfer_Id}": {
- "get": {
- "tags": [
- "transfer"
- ],
- "description": "This method retrieves detailed information regarding a TRANSFER transaction type. A TRANSFER is a monetary transaction type that involves a seller transferring money to eBay for reimbursement of one or more charges. For example, when a seller reimburses eBay for a buyer refund.
If an ID is passed into the URI that is an identifier for another transaction type, this call will return an http status code of 404 Not found.",
- "operationId": "getTransfer",
- "parameters": [
- {
- "name": "transfer_Id",
- "in": "path",
- "description": "The unique identifier of the TRANSFER transaction type you wish to retrieve.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Transfer"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request"
- },
- "404": {
- "description": "Not found.",
- "x-response-codes": {
- "errors": {
- "135012": {
- "domain": "API_FINANCES",
- "category": "REQUEST",
- "description": "The transfer id was not found."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "135000": {
- "domain": "API_FINANCES",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ "description": "This type defines a summarized view of earnings information derived from one order. It defines fields that provides a summarized view of earnings information derived from one order including aggregated financial values for gross amount, expenses, earnings, and refunds. "
+ },
+ "Error": {
+ "type": "object",
+ "properties": {
+ "category": {
+ "type": "string",
+ "description": "Identifies the type of erro."
+ },
+ "domain": {
+ "type": "string",
+ "description": "Name for the primary system where the error occurred. This is relevant for application errors."
+ },
+ "errorId": {
+ "type": "integer",
+ "description": "A unique number to identify the error.",
+ "format": "int32"
+ },
+ "inputRefIds": {
+ "type": "array",
+ "description": "An array of request elements most closely associated to the error.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "longMessage": {
+ "type": "string",
+ "description": "A more detailed explanation of the error."
+ },
+ "message": {
+ "type": "string",
+ "description": "Information on how to correct the problem, in the end user's terms and language where applicable."
+ },
+ "outputRefIds": {
+ "type": "array",
+ "description": "An array of request elements most closely associated to the error.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "parameters": {
+ "type": "array",
+ "description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.",
+ "items": {
+ "$ref": "#/components/schemas/ErrorParameter"
+ }
+ },
+ "subdomain": {
+ "type": "string",
+ "description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc."
+ }
+ },
+ "description": "This type defines the fields that can be returned in an error."
+ },
+ "ErrorParameter": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "The object of the error."
+ },
+ "value": {
+ "type": "string",
+ "description": "The value of the object."
+ }
}
- }
+ },
+ "Expense": {
+ "type": "object",
+ "properties": {
+ "currency": {
+ "type": "string",
+ "description": "This field shows the three-letter currency code that represents the currency used for all of the order expenses For implementation help, refer to eBay API documentation"
+ },
+ "donations": {
+ "type": "array",
+ "description": "This array shows the amount(s) of one or more donations that are submitted to eBay charity organizations for one or more orders.
Note: Donations are always tied to specific items. When an item is listed with a charity contribution (for example, 10%), the donation is calculated per item at the time of sale. Order earnings factor in only the items within the order that are eligible for donation.
",
+ "items": {
+ "$ref": "#/components/schemas/OrderEarningFee"
+ }
+ },
+ "marketplaceFees": {
+ "type": "array",
+ "description": "This array shows the type and amount(s) of marketplace fees that were charged against one or more orders.",
+ "items": {
+ "$ref": "#/components/schemas/OrderEarningFee"
+ }
+ },
+ "shippingLabels": {
+ "description": "This container shows the total amount paid by the seller for eBay shipping labels for one or more orders.
Note: Charges and credits for shipping labels purchased with non-eBay payment methods (for example, PayPal) are excluded from the order earnings calculation.
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "value": {
+ "type": "string",
+ "description": "This field shows the total expenses including charges and credits associated for one or more orders based on the order creation time period chosen."
+ }
+ },
+ "description": "This type defines provides the total expenses associated with an order. Expenses represent cost components that reduce the seller's gross earnings and may include deductions such as marketplace fees, eBay shipping labels, and donations, applied during order processing."
+ },
+ "Fee": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "The monetary amount charged for the fee.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "feeJurisdiction": {
+ "description": "This type defines the jurisdiction associated with a fee. It identifies the geographic or regulatory context under which a specific fee is applied to an order.",
+ "$ref": "#/components/schemas/FeeJurisdiction"
+ },
+ "feeMemo": {
+ "type": "string",
+ "description": "A descriptive message that provides additional context about the fee applied to the order."
+ },
+ "feeType": {
+ "type": "string",
+ "description": "The enumeration value returned here indicates the type of fee that was deducted from the seller payout. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used for provide information about a fee that is charged against an order."
+ },
+ "FeeJurisdiction": {
+ "type": "object",
+ "properties": {
+ "regionName": {
+ "type": "string",
+ "description": "The name of the region to which the fee applies.
The set of valid regionName values returned is determined by the corresponding regionType value.
Note: Currently supported regionName values are standard two-character country or state codes.
Typical examples include:- MX (Mexico)
- IN (India)
- US (United States)
- CA (California)
- VT (Vermont)
- ME (Maine)
"
+ },
+ "regionType": {
+ "type": "string",
+ "description": "This enumeration value indicates the type of region that the fee jurisdiction represents, such as a country or a state. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type defines the jurisdiction information associated with a fee, identifying the geographic or regulatory region under which the fee is applied."
+ },
+ "FundingSource": {
+ "type": "object",
+ "properties": {
+ "brand": {
+ "type": "string",
+ "description": "The brand name of the credit card or the name of the financial institution that is the source of payment. This field may not be populated for other funding sources."
+ },
+ "memo": {
+ "type": "string",
+ "description": "This field provides a note about the funding source. If the seller's credit card or bank account is the funding source, this field might contain the last four digits of the credit card or bank account. This field may also be returned as null."
+ },
+ "type": {
+ "type": "string",
+ "description": "The string value returned here indicates the funding source. Possible values include the following:AVAILABLE_FUNDS: transfer is funded with seller payout fundsCREDIT_CARD: transfer is funded with seller's credit cardBANK: transfer is funded with a direct debit to seller's bank account on file with eBayPAY_UPON_INVOICE: eBay will bill the seller for the transfer on the monthly invoice
"
+ }
+ },
+ "description": "This type defines the source of funds used to finance a transfer, such as available seller funds, a credit card, or a bank account."
+ },
+ "OrderEarning": {
+ "type": "object",
+ "properties": {
+ "buyer": {
+ "description": "Information about the buyer associated with the order. Includes buyer name and public user id.",
+ "$ref": "#/components/schemas/BuyerWithId"
+ },
+ "orderCreationDate": {
+ "type": "string",
+ "description": "The date the order was created and payment was successful."
+ },
+ "orderEarningsSummary": {
+ "description": "This container defines a summarized view of earnings information derived from one order. It provides aggregated financial values for order earnings, gross amount, expenses, and refunds. Order earnings includes earnings after deducting expenses and refunds from the gross amount.",
+ "$ref": "#/components/schemas/EarningsSummary"
+ },
+ "orderId": {
+ "type": "string",
+ "description": "The unique identifier of the order."
+ },
+ "orderLastModifiedDate": {
+ "type": "string",
+ "description": "The date when the order was last modified."
+ },
+ "orderSummary": {
+ "description": "The container for order cost details, including line item subtotal, shipping and handling, seller-collected taxes, and any seller applied discounts. Always provided in the listing currency.",
+ "$ref": "#/components/schemas/OrderSummary"
+ }
+ },
+ "description": "This type defines the earnings details for a single order. It includes information associated with the order, such as an informatiuon about the buyer, an order summary, and an order earnings summary."
+ },
+ "OrderEarningFee": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "The monetary amount of the expense.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "feeType": {
+ "type": "string",
+ "description": "The classification of the fee applied to the order. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used to show the fee type and amount of the marketplace fee or donation."
+ },
+ "OrderEarnings": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI for the current page of results."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The maximum number of order earnings records returned in a single page of results.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The URI for the next page of results. This field is only returned if there is a next page of results to retrieve."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of order earnings records skipped before returning the current page of results.",
+ "format": "int32"
+ },
+ "orders": {
+ "type": "array",
+ "description": "The list of order earnings records returned in the current page of results. This array will be returned as empty if no orders match the request criteria.",
+ "items": {
+ "$ref": "#/components/schemas/OrderEarning"
+ }
+ },
+ "prev": {
+ "type": "string",
+ "description": "The URI for the previous page of results. This field is only returned if there is a previous page of results to retrieve."
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of order earnings records that match the request criteria.",
+ "format": "int32"
+ }
+ },
+ "description": "The base response type of the getOrderEarnings method, which includes pagination output fields and a collection of orders that match the request criteria."
+ },
+ "OrderEarningsSummary": {
+ "type": "object",
+ "properties": {
+ "expenses": {
+ "description": "The aggregate amount of expenses for all orders included in the summary.
Note: Expenses are always in the seller's payout currency. Conversion-related fields (such as exchangeRate) in this container do not apply to the order_earnings resource.
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "grossAmount": {
+ "description": "The aggregate gross amount for all orders included in the order earnings summary. This amount equals the item subtotal plus shipping and handling, and any seller-collected taxes paid by the buyer, minus any seller-offered discount.
Note: Gross amount is always in the seller's payout currency. Conversion-related fields (such as exchangeRate) in this container do not apply to the order_earnings resource.
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "orderCount": {
+ "type": "integer",
+ "description": "The total number of orders included in the summary.",
+ "format": "int32"
+ },
+ "orderEarnings": {
+ "description": "The aggregate earnings amount for all orders included in the summary, which includes the amount of order earnings after deducting expenses and any refunds from the gross amount.Note: Order earnings are always in the seller's payout currency. Conversion-related fields (such as exchangeRate) in this container do not apply to the order_earnings resource.
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "refunds": {
+ "description": "The aggregate amount of all refunds issued for the orders included in the summary.
Note: Refunds include gross refunds, gross claims, and gross payment disputes.
Note: Refunds are always in the seller's payout currency. Conversion-related fields (such as exchangeRate) in this container do not apply to the order_earnings resource.
",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "The base response type for the getOrderEarningsSummary method, which includes aggregate order earnings, expenses, gross amount, and order count for orders created within the date range and included in the summary."
+ },
+ "OrderLineItem": {
+ "type": "object",
+ "properties": {
+ "donations": {
+ "type": "array",
+ "description": "The list of donations applied to the line item.
Note: Currently, this array is only returned if the seller chooses to donate a percentage of the sales proceeds to a charitable organization registered with the eBay for Charity program.",
+ "items": {
+ "$ref": "#/components/schemas/Fee"
+ }
+ },
+ "feeBasisAmount": {
+ "description": "This amount is the order's total amount and equals what the buyer has paid. This value includes transactions.amount, totalFeeAmount, eBayCollectedTaxAmount, and shipping charges (if any).",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "lineItemId": {
+ "type": "string",
+ "description": "The unique identifier of an order line item."
+ },
+ "marketplaceFees": {
+ "type": "array",
+ "description": "An array of all fees accrued for the order line item and deducted from a seller payout.",
+ "items": {
+ "$ref": "#/components/schemas/Fee"
+ }
+ }
+ },
+ "description": "This type is used to show the fees and donations that are deducted from a seller payout for each line item in an order."
+ },
+ "OrderSummary": {
+ "type": "object",
+ "properties": {
+ "discounts": {
+ "description": "The total amount of item-level promotions or discounts offered by the seller for a sale (order).",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "itemSubtotal": {
+ "description": "The sum of the listing price(s) for all items in the order, before applying any seller discounts.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "sellerCollectedTaxes": {
+ "description": "The total amount of tax collected by the seller on all sold items for the order.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "shippingAndHandlingCosts": {
+ "description": "The total amount collected from the buyer to cover shipping and handling for all items in the order.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type provides order cost details, including line item subtotal, shipping and handling, seller-collected taxes, and any seller applied discounts. Always provided in the listing currency."
+ },
+ "Payout": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "This is the total amount of the seller payout. The container shows the dollar amount of the payout and the currency used. The value of the payout is always shown, even if the payout has failed.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "bankReference": {
+ "type": "string",
+ "description": "This field contains additional information provided by the bank and passed on by the payment processor; e.g., the manner in which the transaction will appear on the seller's bank statement. The field is returned only when provided by the bank and processor."
+ },
+ "lastAttemptedPayoutDate": {
+ "type": "string",
+ "description": "This timestamp indicates the date/time when eBay last attempted to process a seller payout but it failed. This field is only returned if a seller payout fails, and the payoutStatus value shows RETRYABLE_FAILED or TERMINAL_FAILED. A seller can filter on the lastAttemptedPayoutDate in a getPayouts request."
+ },
+ "payoutDate": {
+ "type": "string",
+ "description": "This timestamp indicates when the seller payout began processing. The following format is used: YYYY-MM-DDTHH:MM:SS.SSSZ. For example, 2015-08-04T19:09:02.768Z. This field is still returned even if the payout was pending but failed (payoutStatus value shows RETRYABLE_FAILED or TERMINAL_FAILED)."
+ },
+ "payoutId": {
+ "type": "string",
+ "description": "The unique identifier of the seller payout. This identifier is generated once eBay begins processing the payout to the seller's bank account."
+ },
+ "payoutInstrument": {
+ "description": "This container provides details about the seller's account that received (or is scheduled to receive) the payout. This container is still returned even if the payout failed.",
+ "$ref": "#/components/schemas/PayoutInstrument"
+ },
+ "payoutMemo": {
+ "type": "string",
+ "description": "This field contains information provided by upstream components, based on internal and external commitments. A typical message would contain the expected arrival time of the payout."
+ },
+ "payoutReference": {
+ "type": "string",
+ "description": "This field contains the unique identifier for the Payout Reference. In split-payout cases, this is the unique identifier reference (not true payout). This field is only returned and will show the associated true(actual) payout id(s) when sellers in Mainland China enable split payouts between a Payoneer account and/or a bank account.
Note: Split-payout functionality will only be available to mainland China sellers."
+ },
+ "payoutStatus": {
+ "type": "string",
+ "description": "This enumeration value indicates the current status of the seller payout. For a successful payout, the value returned will be SUCCEEDED. See the PayoutStatusEnum type for more details on each payout status value. For implementation help, refer to eBay API documentation"
+ },
+ "payoutStatusDescription": {
+ "type": "string",
+ "description": "This field provides more details about the current status of payout. The description returned here will correspond with enumeration value returned in the payoutStatus field. The following shows what description text might appear based on the different payoutStatus values:INITIATED: Preparing to sendSUCCEEDED: Funds sentREVERSED: Waiting to retry : Money rejected by seller's bankRETRYABLE_FAILED: Waiting to retryTERMINAL_FAILED: Payout failed
"
+ },
+ "totalAmount": {
+ "description": "This container indicates the sum of a seller's net payout amount plus the EXPRESS_PAYOUT_FEE charged by eBay. The is expressed as a numeric value and the currency used.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "totalFee": {
+ "description": "This container indicates the amount of the EXPRESS_PAYOUT_FEE charged by eBay when a seller requests payout to a debit card. The fee is expressed as a numeric value and the currency used.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "totalFeeDetails": {
+ "type": "array",
+ "description": "This array indicates all payout fees associated with a payout, including the fee type, amount, value, and currency.",
+ "items": {
+ "$ref": "#/components/schemas/Fee"
+ }
+ },
+ "transactionCount": {
+ "type": "integer",
+ "description": "This integer value indicates the number of monetary transactions (all orders, refunds, and credits, etc.) that have occurred with the corresponding payout. Its value should always be at least 1, since there is at least one order per seller payout.
For split payouts, each of the two sibling payouts would be considered its own transaction. Because of this, if a seller had a payout for one order, but split the order between two accounts, the value would be 2 instead of 1.
Note: Split-payout functionality is only applicable to mainland China sellers. ",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used to express the details of one seller payout that is returned with the getPayout or getPayouts methods."
+ },
+ "PayoutDetails": {
+ "type": "object",
+ "properties": {
+ "payoutIds": {
+ "type": "array",
+ "description": "This array indicates the list of true(actual) payout ids associated with a split payout. These values can be used as a path parameter for the getPayout method to retrieve details on the associated payouts.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "payoutReference": {
+ "type": "string",
+ "description": "This field contains the unique identifier for the Payout Reference. In split-payout cases, this is the unique identifier reference (not true payout). This field is only returned and will show the associated true(actual) payout id(s) when sellers in Mainland China enable split payouts between a Payoneer account and/or a bank account. This value can be used by the filter query parameter of the getPayouts method to get the monetary details of each true(actual) payout associated with the payoutReference.
Note:Split-payout functionality will only be available to mainland China sellers."
+ }
+ },
+ "description": "This type provide payout details for a split-payout case. This type is only applicable for split payouts."
+ },
+ "PayoutInstrument": {
+ "type": "object",
+ "properties": {
+ "accountLastFourDigits": {
+ "type": "string",
+ "description": "This value is the last four digits of the account that the seller uses to receive the payout. This may be the last four digits of a bank account, a debit card, or a payment processor account such as Payoneer."
+ },
+ "instrumentType": {
+ "type": "string",
+ "description": "This value indicates the type of account that received the payout. The value returned in this field may be:
BANK: indicates that the payout was made to a seller's bank account.CARD: indicates that the payout went to a seller's debit card- The name of a digital wallet provider or payment processor (e.g.,
PAYONEER)
Note: Only Payoneer is currently supported for sellers in mainland China. Card payouts are not currently available for sellers in mainland China."
+ },
+ "nickname": {
+ "type": "string",
+ "description": "When instrumentType returns BANK, this value is the seller-provided nickname that the seller uses to represent the bank account that receives the payout.
When instrumentType returns CARD, this value is the debit card network for the debit card that receives the payout.
When instrumentType returns a provider of digital wallet or payment processing services, the value returned is the name of the service provider (e.g., PAYONEER).
Note: Card payouts are not currently available for sellers in mainland China."
+ },
+ "payoutPercentage": {
+ "type": "string",
+ "description": "This value indicates the current payout percentage allocated to a payout instrument. For example, 50 indicates that 50% of the payout goes to the instrument.
This field will be returned even when 100% of the payout funds are going to one payout instrument.
This field is only returned to sellers in mainland China."
+ }
+ },
+ "description": "This type is used to provide details about one or two of the seller's accounts that are enabled to receive payouts."
+ },
+ "PayoutSummaryResponse": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "This container shows the total value (and currency type used) of the seller payouts that match the input criteria. This field is not returned if there are no payouts that match the input criteria.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "payoutCount": {
+ "type": "integer",
+ "description": "This integer value indicates the total count of payouts to the seller that match the input criteria. This field is always returned, even if there are no payouts that match the input criteria (its value will show 0).",
+ "format": "int32"
+ },
+ "transactionCount": {
+ "type": "integer",
+ "description": "This integer value indicates the total count of monetary transactions (order payments, buyer refunds, and seller credits) associated with the payouts that match the input criteria. This field is always returned, even if there are no payouts that match the input criteria (its value will show 0). If there is at least one payout that matches the input criteria, the value in this field will be at least 1.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is the base response type of the getPayoutSummary method, and contains the total count of seller payouts (that match the input criteria), the total count of monetary transactions (order payment, buyer refunds, or seller credits) associated with those payouts, and the total value of those seller payouts."
+ },
+ "Payouts": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the getPayouts call request that produced the current page of the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The maximum number of payouts that may be returned per page of the result set. The limit value can be passed in as a query parameter, or if omitted, its value defaults to 20.
Note: If this is the last or only page of the result set, the page may contain fewer payouts than the limit value. To determine the number of pages in a result set, divide the total value (total number of payouts matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total payouts) and the limit value was 50 (show 50 payouts per page), the total number of pages in the result set is three, so the seller would have to make three separate getPayouts calls to view all payouts matching the input criteria.
Maximum: 200
Default: 20",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The getPayouts call URI to use if you wish to view the next page of the result set.
This field is only returned if there is a next page of results to view based on the current input criteria."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "This integer value indicates the actual position that the first payout returned on the current page has in the results set. So, if you wanted to view the 11th payout of the result set, you would set the offset value in the request to 10.
In the request, you can use the offset parameter in conjunction with the limit parameter to control the pagination of the output. For example, if offset is set to 30 and limit is set to 10, the call retrieves payouts 31 thru 40 from the resulting collection of payouts.
Note: This feature employs a zero-based list, where the first item in the list has an offset of 0.
Default: 0 (zero)",
+ "format": "int32"
+ },
+ "payouts": {
+ "type": "array",
+ "description": "An array of one or more payouts that match the input criteria. Details for each payout include the unique identifier of the payout, the status of the payout, the amount of the payout, and the number of monetary transactions associated with the payout.",
+ "items": {
+ "$ref": "#/components/schemas/Payout"
+ }
+ },
+ "prev": {
+ "type": "string",
+ "description": "The getPayouts call URI to use if you wish to view the previous page of the result set.
This field is only returned if there is a previous page of results to view based on the current input criteria."
+ },
+ "total": {
+ "type": "integer",
+ "description": "This integer value is the total number of payouts in the results set based on the current input criteria. Based on the total number of payouts that match the criteria, and on the limit and offset values, there may be additional pages in the results set.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is the base response type of the getPayouts method, and contains an array of one or more payouts (that match the input criteria), the total count of payouts in the response, and various pagination data for the results set."
+ },
+ "Reference": {
+ "type": "object",
+ "properties": {
+ "referenceId": {
+ "type": "string",
+ "description": "The identifier of the transaction as specified by the referenceType. For example, with a referenceType of item_id, the referenceId refers to a unique item. This item may have several NON_SALE_CHARGE transactions."
+ },
+ "referenceType": {
+ "type": "string",
+ "description": "An enumeration value that identifies the reference type associated with the referenceId. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This field is returned for NON_SALE_CHARGE transactions that contain non-transactional seller fees."
+ },
+ "SellerFundsSummaryResponse": {
+ "type": "object",
+ "properties": {
+ "availableFunds": {
+ "description": "This field represents the total amount of order funds that are available for a payout, but processing for a seller payout has not yet begun. If a seller wants to get more details on sales transactions that have yet to be processed, the seller can use the getTransactions method, and use the transactionStatus filter with its value set to FUNDS_AVAILABLE_FOR_PAYOUT.
This container will return 0.0 with the appropriate payout currency if there are no funds available to be processed for a payout.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "fundsOnHold": {
+ "description": "This field represents the total amount of order funds on hold. Seller payment holds can occur for different reasons. If a seller wants to get more details on sales transactions where funds are currently on hold, the seller can use the getTransactions method, and use the transactionStatus filter with its value set to FUNDS_ON_HOLD.
This container will return 0.0 with the appropriate payout currency if there are no seller payment holds that will eventually be processed for a payout.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "processingFunds": {
+ "description": "This field represents the total amount of order funds being prepared and processed for a seller payout. If a seller wants to get more details on sales transactions that are being processed, the seller can use the getTransactions method, and use the transactionStatus filter with its value set to FUNDS_PROCESSING.
This container will return 0.0 with the appropriate payout currency if there are no funds available to be processed for a payout.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "totalFunds": {
+ "description": "This field represents the total amount of order funds still due to be distributed to the seller through a seller payout. This field should equal the sum of the amounts returned in the following fields:
- processingFunds
- availableFunds
- fundsOnHold
If no payout funds are due to the seller, a 204 - No Content status code will be returned along with an empty payload.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type is used by the response payload of the getSellerFundsSummary method. All of the funds returned in getSellerFundsSummary are funds that have not yet been paid to the seller through a seller payout. If there are no funds that are pending, on hold, or being processed for the seller's account, no response payload is returned, and an http status code of 204 - No Content is returned instead."
+ },
+ "Tax": {
+ "type": "object",
+ "properties": {
+ "taxType": {
+ "type": "string",
+ "description": "The type of tax applied to the transaction. For implementation help, refer to eBay API documentation"
+ },
+ "amount": {
+ "description": "The monetary amount of the tax applied.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type defines tax information associated with a transaction."
+ },
+ "Transaction": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "This container shows the dollar value and currency type of the monetary transaction. This field is always returned even when eBay has yet to initiate a payout for the order.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "bookingEntry": {
+ "type": "string",
+ "description": "The enumeration value returned in this field indicates if the monetary transaction amount is a (CREDIT) or a (DEBIT) to the seller's account. Typically, the SALE and CREDIT transaction types are credits to the seller's account, and the REFUND, DISPUTE, SHIPPING_LABEL, and TRANSFER transaction types are debits to the seller's account. For implementation help, refer to eBay API documentation"
+ },
+ "buyer": {
+ "description": "This is the unique eBay user ID for the buyer who purchased the order. This field is not returned for TRANSFER monetary transaction types.",
+ "$ref": "#/components/schemas/Buyer"
+ },
+ "eBayCollectedTaxAmount": {
+ "description": "This is the amount of sales tax that has been collected by eBay for an order.
Note: Sales tax applies only to SALE and REFUND transactions (transactionType).",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "feeJurisdiction": {
+ "description": "This container stores information about region-specific fees that are charged to sellers.
This is returned for fees (i.e., FeeTypeEnum values,) that are mandated by a seller's governing jurisdiction.
For example:INCOME_TAX_WITHHOLDINGTAX_DEDUCTION_AT_SOURCEVAT_WITHHOLDING
",
+ "$ref": "#/components/schemas/FeeJurisdiction"
+ },
+ "feeType": {
+ "type": "string",
+ "description": "The enumeration value returned in this field indicates the type of fee that was deducted from the seller payout. For implementation help, refer to eBay API documentation"
+ },
+ "orderId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay order associated with the monetary transaction."
+ },
+ "orderLineItems": {
+ "type": "array",
+ "description": "This array either shows the order line item transactional fees related to a SALE transaction and deducted from the payout associated with that order, or it shows the transactional fee credits going back to the seller in the case of a REFUND transaction.
Note: In certain circumstances, transactional fees like FINAL_VALUE_FEE and FINAL_VALUE_FEE_FIXED_PER_ORDER are not deducted from a seller payout, but instead they are billed to the seller's account as \"non-sale charges\". When this happens, the SALE transaction entity will not have these fees under the orderLineItems array, but they will appear as separate NON_SALE_CHARGE transactions. When this happens, and you want to see those transactional fees for the order, one thing you can do is make another call to getTransactions and filter against the orderId. In the response, you will see the SALE transaction and the NON_SALE_CHARGE transactions applied against the order. See Sample 6: Get transactional fees for an order and Sample 10: Get non-sale charges for an order for examples.",
+ "items": {
+ "$ref": "#/components/schemas/OrderLineItem"
+ }
+ },
+ "paymentsEntity": {
+ "type": "string",
+ "description": "This string value indicates the entity that is processing the payment."
+ },
+ "payoutDetails": {
+ "description": "This container provides the payout details for a split-payout case. This container is only returned for split-payout use cases.",
+ "$ref": "#/components/schemas/PayoutDetails"
+ },
+ "payoutId": {
+ "type": "string",
+ "description": "The unique identifier of the seller payout associated with the monetary transaction. This identifier is generated once eBay begins processing the payout for the corresponding order. This field will not be returned if eBay has not yet begun processing the payout for an order.
This value can be used by the filter query parameter to get monetary transactions associated with the true(actual) payout associated with the PayoutId.
Note: In case of a split payout, always pick the first true(actual) payout id. "
+ },
+ "references": {
+ "type": "array",
+ "description": "This field contains reference information for the transaction fee. This includes an ID and the type of ID provided (such as item ID).",
+ "items": {
+ "$ref": "#/components/schemas/Reference"
+ }
+ },
+ "salesRecordReference": {
+ "type": "string",
+ "description": "The Sales Record Number associated with a sales order. Sales Record Numbers are Selling Manager/Selling Manager Pro identifiers that are created at order checkout.
Note: For all orders originating after February 1, 2020, a value of 0 will be returned in this field. The Sales Record Number field has also been removed from Seller Hub. Instead of salesRecordReference, depend on orderId instead as the identifier of the order. The salesRecordReference field has been scheduled for deprecation, and a date for when this field will no longer be returned at all will be announced soon."
+ },
+ "taxes": {
+ "type": "array",
+ "description": "This array shows the tax type and amount applicable to the transaction.
Note: Currently, this array is only returned for tax charged against a purchased eBay shipping label.",
+ "items": {
+ "$ref": "#/components/schemas/Tax"
+ }
+ },
+ "totalFeeAmount": {
+ "description": "This amount is the total amount of selling fees paid for order. A breakdown of fees for each order line item can be found in the orderLineItems array.
This field is even returned if it is 0.0 (no fees deducted from seller payout).",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "totalFeeBasisAmount": {
+ "description": "This amount is the total amount for the order before selling fees are deducted from the seller payout associated with the order.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "transactionDate": {
+ "type": "string",
+ "description": "This timestamp indicates when the monetary transaction (order purchase, buyer refund, seller credit) occurred. The following (UTC) format is used: YYYY-MM-DDTHH:MM:SS.SSSZ. For example, 2015-08-04T19:09:02.768Z."
+ },
+ "transactionId": {
+ "type": "string",
+ "description": "This field, when combined with the transactionType field, provide a unique identifier of the monetary transaction. A monetary transaction can be a sales order, an order refund to the buyer, a credit to the seller's account, a debit to the seller for the purchase of a shipping label, or a transaction where eBay recouped money from the seller if the seller lost a buyer-initiated payment dispute."
+ },
+ "transactionMemo": {
+ "type": "string",
+ "description": "This field applies to shipping label transactions, sales transactions where payout is on hold, and non-sale charge fees. The following are examples of how the field is used for each transaction type:- Shipping label purchase: the transactionMemo field gives details about a purchase, a refund, or a price adjustment to the cost of the shipping label.
- Sales transactions with funds on hold: the transactionMemo field provides information on the reason for the hold or when the hold will be released (e.g., \"Funds on hold. Estimated release on Jun 1\").
- Non-sale charge fees: the transactionMemo field will provide the type of fee that was charged, such as Promoted Offsite Fee.
This field is only returned if applicable/available."
+ },
+ "transactionStatus": {
+ "type": "string",
+ "description": "This enumeration value indicates the current status of the seller payout associated with the monetary transaction. See the TransactionStatusEnum type for more information on the different states. For implementation help, refer to eBay API documentation"
+ },
+ "transactionType": {
+ "type": "string",
+ "description": "This enumeration value indicates the type of monetary transaction. Examples of monetary transactions include a buyer's payment for an order, a refund to the buyer for a returned item or cancelled order, or a credit issued by eBay to the seller's account. For a complete list of monetary transaction types within the Finances API, see the TransactionTypeEnum type. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used to express the details of one of the following monetary transactions: a buyer's payment for an order, a refund to the buyer for a returned item or cancelled order, or a credit issued by eBay to the seller's account."
+ },
+ "TransactionSummaryResponse": {
+ "type": "object",
+ "properties": {
+ "adjustmentAmount": {
+ "description": "Total adjustment amount for given payee within a specified period.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "adjustmentBookingEntry": {
+ "type": "string",
+ "description": "The credit debit sign indicator for adjustment. For implementation help, refer to eBay API documentation"
+ },
+ "adjustmentCount": {
+ "type": "integer",
+ "description": "Total adjustment count for given payee within a specified period.",
+ "format": "int32"
+ },
+ "balanceTransferAmount": {
+ "description": "The total balance transfer amount for given payee within the specified period.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "balanceTransferBookingEntry": {
+ "type": "string",
+ "description": "The credit debit sign indicator for the balance transfer. For implementation help, refer to eBay API documentation"
+ },
+ "balanceTransferCount": {
+ "type": "integer",
+ "description": "The total balance transfer count for given payee within the specified period.",
+ "format": "int32"
+ },
+ "creditAmount": {
+ "description": "This amount is the total dollar value of all the seller's sales and/or credits that match the input criteria.
Note: Unless the transactionType filter is used in the request to retrieve a specific type of monetary transaction, the creditCount and creditAmount fields account for both order sales and seller credits (the count and value is not distinguished between the two monetary transaction types).
If there are no sales/credits (creditCount=0), this container is not returned.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "creditBookingEntry": {
+ "type": "string",
+ "description": "The enumeration value indicates whether the dollar amount in the creditAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be CREDIT. For implementation help, refer to eBay API documentation"
+ },
+ "creditCount": {
+ "type": "integer",
+ "description": "This integer value indicates the total number of the seller's sales and/or credits that match the input criteria.
Note: Unless the transactionType filter is used in the request to retrieve a specific type of monetary transaction (sale, buyer refund, or seller credit), the creditCount and creditAmount fields account for both order sales and seller credits (the count and value is not distinguished between the two monetary transaction types).
This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to either REFUND, DISPUTE, or SHIPPING_LABEL.",
+ "format": "int32"
+ },
+ "disputeAmount": {
+ "description": "This amount is the total dollar value associated with any existing payment disputes that have been initiated by one or more buyers. Only the orders that match the input criteria are considered. The Payment Disputes methods in the Fulfillment API can be used by the seller to retrieve more information about any payment disputes.
If there are no payment disputes (disputeCount=0), this container is not returned.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "disputeBookingEntry": {
+ "type": "string",
+ "description": "The enumeration value indicates whether the dollar amount in the disputeAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT, but its possible that CREDIT could be returned if the seller contested one or more payment disputes and won the dispute. For implementation help, refer to eBay API documentation"
+ },
+ "disputeCount": {
+ "type": "integer",
+ "description": "This integer value indicates the total number of payment disputes that have been initiated by one or more buyers. Only the orders that match the input criteria are considered. The Payment Disputes methods in the Fulfillment API can be used by the seller to retrieve more information about any payment disputes.
This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to any value other than DISPUTE.",
+ "format": "int32"
+ },
+ "loanRepaymentAmount": {
+ "description": "The sum of all LOAN_REPAYMENT transactions (i.e., debit and credit,) that match the input criteria.
For example, within a specified transactionDate range, three LOAN_REPAYMENT transactions are identified:- DEBIT of 15.00 USD
- DEBIT of 10.00 USD
- CREDIT of 5.00 USD
The net amount of these three transactions is a DEBIT of 20.00 USD to the seller's account. Therefore, the value returned for loanRepaymentAmount will be 20.00 USD.
Note: For this example:- The value returned for
loanRepaymentCount will be 3 - The
loanRepaymentBookingEntry will be DEBIT
If there are no transactions that match the input criteria (i.e., loanRepaymentCount=0,) this container is not returned.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "loanRepaymentBookingEntry": {
+ "type": "string",
+ "description": "The enumeration value indicates whether the loanRepaymentAmount is a DEBIT against, or a CREDIT to, the sellers's account.
For most loanRepaymentAmount transactions, loanRepaymentBookingEntry will be DEBIT. However, if a loan repayment transaction is reversed, that transaction will be shown as a CREDIT. For implementation help, refer to eBay API documentation"
+ },
+ "loanRepaymentCount": {
+ "type": "integer",
+ "description": "This integer value indicates the total number of LOAN_REPAYMENT transactions (i.e., DEBIT and CREDIT,) that match the input criteria.
This field is generally returned even if it equals 0. However it will not be returned if a transactionType filter is used and its value has been set to any enumeration value other than LOAN_REPAYMENT.",
+ "format": "int32"
+ },
+ "nonSaleChargeAmount": {
+ "description": "The total non-sale charge amount for given payee within a specified period.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "nonSaleChargeBookingEntry": {
+ "type": "string",
+ "description": "The credit/debit sign indicator for the non-sale charge. For implementation help, refer to eBay API documentation"
+ },
+ "nonSaleChargeCount": {
+ "type": "integer",
+ "description": "The total non-sale charge count for given payee within a specified period.",
+ "format": "int32"
+ },
+ "onHoldAmount": {
+ "description": "This amount is the total dollar value of order sales where the associated funds are on hold. Only the orders that match the input criteria are considered.
If there are no seller payment holds (onHoldCount=0), this container is not returned.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "onHoldBookingEntry": {
+ "type": "string",
+ "description": "The enumeration value indicates whether the dollar amount in the onHoldAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be CREDIT, since on-hold funds should eventually be released as part of a payout to the seller once the hold is cleared. For implementation help, refer to eBay API documentation"
+ },
+ "onHoldCount": {
+ "type": "integer",
+ "description": "This integer value indicates the total number of order sales where the associated funds are on hold. Only the orders that match the input criteria are considered.
This field is generally returned, even if 0, but it will not be returned if a transactionStatus filter is used, and its value is set to any value other than FUNDS_ON_HOLD.",
+ "format": "int32"
+ },
+ "purchaseAmount": {
+ "description": "Note: The PURCHASE transaction type is currently only applicable in the US marketplace.
This amount is the total dollar value of all the purchases that have been initiated by a seller using spendable funds that match the input criteria.
If there are no transactions that match the input criteria (i.e., purchaseCount=0), this container will not be returned.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "purchaseBookingEntry": {
+ "type": "string",
+ "description": "Note: The PURCHASE transaction type is currently only applicable in the US marketplace.
This enumeration value indicates whether the dollar amount in the purchase field is a charge (debit) to the seller or a credit. For implementation help, refer to eBay API documentation"
+ },
+ "purchaseCount": {
+ "type": "integer",
+ "description": "Note: The PURCHASE transaction type is currently only applicable in the US marketplace.
This integer value indicates the total number of purchases that have been initiated by a seller using spendable funds that match the input criteria.
This field is generally returned, even if it equals 0. However, it will not be returned if a transactionType filter is used and its value has been set to any enumeration value other than PURCHASE.",
+ "format": "int32"
+ },
+ "refundAmount": {
+ "description": "This amount is the total dollar value of buyer refunds that match the input criteria.
If there are no refunds (refundCount=0), this container is not returned.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "refundBookingEntry": {
+ "type": "string",
+ "description": "The enumeration value indicates whether the dollar amount in the refundAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT since this a refund from the seller to the buyer. For implementation help, refer to eBay API documentation"
+ },
+ "refundCount": {
+ "type": "integer",
+ "description": "This integer value indicates the total number of buyer refunds that match the input criteria.
This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to any value other than REFUND.",
+ "format": "int32"
+ },
+ "shippingLabelAmount": {
+ "description": "This is the total dollar value of the eBay shipping labels purchased by the seller.
Note: eBay SHIPPING_LABEL transactions paid through PayPal are not currently supported by the Finances API, so those transactions will not be reflected in the amounts returned in this container.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "shippingLabelBookingEntry": {
+ "type": "string",
+ "description": "The enumeration value indicates whether the dollar amount in the shippingLabelAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT, as eBay will charge the seller when eBay shipping labels are purchased, but it can be CREDIT if the seller was refunded for a shipping label or was possibly overcharged for a shipping label.
Note: eBay SHIPPING_LABEL transactions paid through PayPal are not currently supported by the Finances API, so those transactions will not be reflected in this field. For implementation help, refer to eBay API documentation"
+ },
+ "shippingLabelCount": {
+ "type": "integer",
+ "description": "This is the total number of eBay shipping labels purchased by the seller. The count returned here may depend on the specified input criteria.
Note: eBay SHIPPING_LABEL transactions paid through PayPal are not currently supported by the Finances API, so those transactions will not be reflected in the count returned in this container.",
+ "format": "int32"
+ },
+ "transferAmount": {
+ "description": "This amount is the total dollar value of buyer refund transfers that match the input criteria.
If there are no transfers (refundCount=0), this container is not returned.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "transferBookingEntry": {
+ "type": "string",
+ "description": "The enumeration value indicates whether the dollar amount in the transferAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT since this a seller reimbursement to eBay for buyer refunds. For implementation help, refer to eBay API documentation"
+ },
+ "transferCount": {
+ "type": "integer",
+ "description": "This integer value indicates the total number of buyer refund transfers that match the input criteria.
This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to any value other than TRANSFER.",
+ "format": "int32"
+ },
+ "withdrawalAmount": {
+ "description": "This amount is the total dollar value of on-demand payouts (withdrawals) that match the input criteria.
If there are no withdrawals (withdrawalCount=0), this container is not returned.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "withdrawalBookingEntry": {
+ "type": "string",
+ "description": "The enumeration value indicates whether the dollar amount in the withdrawalAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT since this transaction involves a debit to the seller's available payout funds. For implementation help, refer to eBay API documentation"
+ },
+ "withdrawalCount": {
+ "type": "integer",
+ "description": "This integer value indicates the total number of on-demand payouts (withdrawals) that match the input criteria.
This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to any value other than WITHDRAWAL.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is the base response type of the getTransactionSummary method, and based on the filters that are used in the getTransactionSummary call URI, the response may include total count and amount of the seller's sales and credits, total count and amount of buyer refunds, and total count and amount of seller payment holds."
+ },
+ "Transactions": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the getTransactions method request that produced the current page of the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The maximum number of monetary transactions that may be returned per page of the result set. The limit value can be passed in as a query parameter, or if omitted, its value defaults to 20.
Note: If this is the last or only page of the result set, the page may contain fewer monetary transactions than the limit value. To determine the number of pages in a result set, divide the total value (total number of monetary transactions matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total monetary transactions) and the limit value was 50 (show 50 monetary transactions per page), the total number of pages in the result set is three, so the seller would have to make three separate getTransactions calls to view all monetary transactions matching the input criteria.
Maximum: 200
Default: 20",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The getTransactions method URI to use if you wish to view the next page of the result set.
This field is only returned if there is a next page of results to view based on the current input criteria."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "This integer value indicates the actual position that the first monetary transaction returned on the current page has in the results set. So, if you wanted to view the 11th monetary transaction of the result set, you would set the offset value in the request to 10.
In the request, you can use the offset parameter in conjunction with the limit parameter to control the pagination of the output. For example, if offset is set to 30 and limit is set to 10, the method retrieves monetary transactions 31 thru 40 from the resulting collection of monetary transactions.
Note: This feature employs a zero-based list, where the first item in the list has an offset of 0.
Default: 0 (zero)",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The getTransactions method URI to use if you wish to view the previous page of the result set.
This field is only returned if there is a previous page of results to view based on the current input criteria."
+ },
+ "total": {
+ "type": "integer",
+ "description": "This integer value is the total amount of monetary transactions in the result set based on the current input criteria. Based on the total number of monetary transactions that match the criteria, and on the limit and offset values, there may be additional pages in the results set.",
+ "format": "int32"
+ },
+ "transactions": {
+ "type": "array",
+ "description": "An array of one or more monetary transactions that match the input criteria. Details for each monetary transaction may include the unique identifier of the order associated with the monetary transaction, the status of the transaction, the amount of the order, the order's buyer, and the unique identifier of the payout (if a payout has been initiated/issued for the order).",
+ "items": {
+ "$ref": "#/components/schemas/Transaction"
+ }
+ }
+ },
+ "description": "This is the base response type of the getTransactions method. The getTransactions response includes details on one or more monetary transactions that match the input criteria, as well as pagination data. "
+ },
+ "Transfer": {
+ "type": "object",
+ "properties": {
+ "fundingSource": {
+ "description": "This container provides details about the seller's funding source to reimburse eBay for the transfer, such as a bank account, a credit card, or available seller payout funds.",
+ "$ref": "#/components/schemas/FundingSource"
+ },
+ "transactionDate": {
+ "type": "string",
+ "description": "This timestamp indicates the date/time of the transfer. The following (UTC) format is used: YYYY-MM-DDTHH:MM:SS.SSSZ. For example, 2020-08-04T19:09:02.768Z"
+ },
+ "transferAmount": {
+ "description": "The amount of the transfer being deducted from the funding source.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "transferDetail": {
+ "description": "This container provides more details about the transfer, including details on the charge(s) associated with the transfer. Multiple charges can be addressed with one transfer.",
+ "$ref": "#/components/schemas/TransferDetail"
+ },
+ "transferId": {
+ "type": "string",
+ "description": "The unique identifier of the TRANSFER transaction type. This is the same value that was passed into the end of the call URI."
+ }
+ },
+ "description": "This type is the base response type used by TRANSFER transaction type that is returned in the response."
+ },
+ "TransferDetail": {
+ "type": "object",
+ "properties": {
+ "balanceAdjustment": {
+ "description": "This container shows the seller payout balance that will be applied toward the charges outlined in the charges array.",
+ "$ref": "#/components/schemas/BalanceAdjustment"
+ },
+ "charges": {
+ "type": "array",
+ "description": "This container is an array of one or more charges related to the transfer. Charges can be related to an order cancellation, order return, case, payment dispute, etc.",
+ "items": {
+ "$ref": "#/components/schemas/Charge"
+ }
+ },
+ "totalChargeNetAmount": {
+ "description": "This container shows the total amount that the seller owes for all of the charges outlined in the charges array.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type is used by the transferDetail container, which provides more details about the transfer and the charge(s) associated with the transfer."
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.finances"
- ]
- }
- ]
- }
- },
- "/seller_funds_summary": {
- "get": {
- "tags": [
- "seller_funds_summary"
- ],
- "description": "This method retrieves all pending funds that have not yet been distibuted through a seller payout.
There are no input parameters for this method. The response payload includes available funds, funds being processed, funds on hold, and also an aggregate count of all three of these categories.
If there are no funds that are pending, on hold, or being processed for the seller's account, no response payload is returned, and an http status code of 204 - No Content is returned instead.",
- "operationId": "getSellerFundsSummary",
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/SellerFundsSummaryResponse"
+ "securitySchemes": {
+ "api_auth": {
+ "type": "oauth2",
+ "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
+ "flows": {
+ "authorizationCode": {
+ "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
+ "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
+ "scopes": {
+ "https://api.ebay.com/oauth/api_scope/sell.finances": "View and manage your payment and order information to display this information to you and allow you to initiate refunds using the third party application"
+ }
+ }
}
- }
- }
- },
- "204": {
- "description": "No Content"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "135000": {
- "domain": "API_FINANCES",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.finances"
- ]
- }
- ]
- }
- }
- },
- "components": {
- "schemas": {
- "Amount": {
- "type": "object",
- "properties": {
- "currency": {
- "type": "string",
- "description": "A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type.
Default: The currency of the authenticated user's country. For implementation help, refer to eBay API documentation"
- },
- "convertedFromCurrency": {
- "type": "string",
- "description": "The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency.
This field is only returned if/when currency conversion was applied by eBay. For implementation help, refer to eBay API documentation"
- },
- "convertedFromValue": {
- "type": "string",
- "description": "The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field.
This field is only returned if/when currency conversion was applied by eBay."
- },
- "exchangeRate": {
- "type": "string",
- "description": "The exchange rate used for the monetary conversion. This field shows the exchange rate used to convert the dollar value in the value field from the dollar value in the convertedFromValue field.
This field is only returned when eBay does a currency version, and a currency conversion is generally needed if the buyer is viewing, or has purchased an item on an international site.
This field is only returned if/when currency conversion was applied by eBay."
- },
- "value": {
- "type": "string",
- "description": "The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type."
- }
- },
- "description": "This type is used to express the dollar value and currency used for any transaction retrieved with the Finances API, including an order total, a seller payout, a buyer refund, or a seller credit."
- },
- "BalanceAdjustment": {
- "type": "object",
- "properties": {
- "adjustmentAmount": {
- "description": "The seller payout balance amount that will be applied toward the charges outlined in the charges array.",
- "$ref": "#/components/schemas/Amount"
- },
- "adjustmentType": {
- "type": "string",
- "description": "The enumeration value returned here indicates if the charge is a DEBIT or a CREDIT to the seller. Generally, all transfer transaction types are going to be DEBIT, since the money is being tranferred from the seller to eBay. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used by the balanceAdjustment container, which shows the seller payout balance that will be applied toward the charges outlined in the charges array."
- },
- "Buyer": {
- "type": "object",
- "properties": {
- "username": {
- "type": "string",
- "description": "The eBay user ID of the order's buyer."
- }
- },
- "description": "This type is used to express details about the buyer associated with an order. At this time, the only field in this type is the eBay user ID of the buyer, but more fields may get added at a later date."
- },
- "Charge": {
- "type": "object",
- "properties": {
- "cancellationId": {
- "type": "string",
- "description": "The unique identifier of an order cancellation. This field is only applicable and returned if the charge is related to an order cancellation."
- },
- "caseId": {
- "type": "string",
- "description": "The unique identifier of a case filed against an order. This field is only applicable and returned if the charge is related to a case filed against an order."
- },
- "chargeNetAmount": {
- "description": "This container shows the net amount of the charge, which is the total amount of the charge minus the total amount of fees credited towards this refund as per eBay policy. It is possible for there to be multiple charges from multiple orders with one transfer. The net aggregate amount for all charges found in the charges array can be found in the transferDetail.totalChargeNetAmount container.",
- "$ref": "#/components/schemas/Amount"
- },
- "inquiryId": {
- "type": "string",
- "description": "The unique identifier of an Item Not Received (INR) inquiry filed against an order. This field is only applicable and returned if the charge is related to has an INR inquiry filed against the order."
- },
- "orderId": {
- "type": "string",
- "description": "The unique identifier of the order that is associated with the charge."
- },
- "paymentDisputeId": {
- "type": "string",
- "description": "The unique identifier of a third-party payment dispute filed against an order. This occurs when the buyer files a dispute against the order with their payment provider, and then the dispute comes into eBay's system. This field is only applicable and returned if the charge is related to a third-party payment dispute filed against an order."
- },
- "refundId": {
- "type": "string",
- "description": "The unique identifier of a buyer refund associated with the charge."
- },
- "returnId": {
- "type": "string",
- "description": "The unique identifier of an order return. This field is only applicable and returned if the charge is related to an order that was returned by the buyer."
- }
- },
- "description": "This type is used by the charge container, which is an array of one or more charges related to the transfer."
- },
- "Error": {
- "type": "object",
- "properties": {
- "category": {
- "type": "string",
- "description": "Identifies the type of erro."
- },
- "domain": {
- "type": "string",
- "description": "Name for the primary system where the error occurred. This is relevant for application errors."
- },
- "errorId": {
- "type": "integer",
- "description": "A unique number to identify the error.",
- "format": "int32"
- },
- "inputRefIds": {
- "type": "array",
- "description": "An array of request elements most closely associated to the error.",
- "items": {
- "type": "string"
- }
- },
- "longMessage": {
- "type": "string",
- "description": "A more detailed explanation of the error."
- },
- "message": {
- "type": "string",
- "description": "Information on how to correct the problem, in the end user's terms and language where applicable."
- },
- "outputRefIds": {
- "type": "array",
- "description": "An array of request elements most closely associated to the error.",
- "items": {
- "type": "string"
- }
- },
- "parameters": {
- "type": "array",
- "description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.",
- "items": {
- "$ref": "#/components/schemas/ErrorParameter"
- }
- },
- "subdomain": {
- "type": "string",
- "description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc."
- }
- },
- "description": "This type defines the fields that can be returned in an error."
- },
- "ErrorParameter": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "The object of the error."
- },
- "value": {
- "type": "string",
- "description": "The value of the object."
- }
- }
- },
- "Fee": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "The amount of the fee.",
- "$ref": "#/components/schemas/Amount"
- },
- "feeMemo": {
- "type": "string",
- "description": "A description of the fee that was deducted from the seller payout."
- },
- "feeType": {
- "type": "string",
- "description": "The enumeration value returned here indicates the type of fee that was deducted from the seller payout. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used to display fees that are automatically deducted from seller payouts."
- },
- "FundingSource": {
- "type": "object",
- "properties": {
- "brand": {
- "type": "string",
- "description": "The brand name of the credit card or the name of the financial institution that is the source of payment. This field may not be populated for other funding sources."
- },
- "memo": {
- "type": "string",
- "description": "This field provides a note about the funding source. If the seller's credit card or bank account is the funding source, this field might contain the last four digits of the credit card or bank account. This field may also be returned as null."
- },
- "type": {
- "type": "string",
- "description": "The string value returned here indicates the funding source. Possible values include the following:AVAILABLE_FUNDS: transfer is funded with seller payout fundsCREDIT_CARD: transfer is funded with seller's credit cardBANK: transfer is funded with a direct debit to seller's bank account on file with eBayPAY_UPON_INVOICE: eBay will bill the seller for the transfer on the monthly invoice
"
- }
- },
- "description": "This type provided details on the funding source for the transfer."
- },
- "OrderLineItem": {
- "type": "object",
- "properties": {
- "feeBasisAmount": {
- "description": "This is the total amount of fees accrued for the order line item and deducted from a seller payout. All of the fees under the marketplaceFees container should equal this amount.",
- "$ref": "#/components/schemas/Amount"
- },
- "lineItemId": {
- "type": "string",
- "description": "The unique identifier of an order line item."
- },
- "marketplaceFees": {
- "type": "array",
- "description": "An array of all fees accrued for the order line item and deducted from a seller payout.",
- "items": {
- "$ref": "#/components/schemas/Fee"
- }
- }
- },
- "description": "This type is used to show the fees that are deducted from a seller payout for each line item in an order."
- },
- "Payout": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "This the total amount of the seller payout. The container shows the dollar amount of the payout and the currency used. The value of the payout is always shown, even if the payout has failed.",
- "$ref": "#/components/schemas/Amount"
- },
- "bankReference": {
- "type": "string",
- "description": "This field contains additional information provided by the bank and passed on by the payment processor; e.g., the manner in which the transaction will appear on the seller's bank statement. The field is returned only when provided by the bank and processor."
- },
- "lastAttemptedPayoutDate": {
- "type": "string",
- "description": "This timestamp indicates the date/time when eBay last attempted to process a seller payout but it failed. This field is only returned if a seller payout fails, and the payoutStatus value shows RETRYABLE_FAILED or TERMINAL_FAILED. A seller can filter on the lastAttemptedPayoutDate in a getPayouts request."
- },
- "payoutDate": {
- "type": "string",
- "description": "This timestamp indicates when the seller payout began processing. The following format is used: YYYY-MM-DDTHH:MM:SS.SSSZ. For example, 2015-08-04T19:09:02.768Z. This field is still returned even if the payout was pending but failed (payoutStatus value shows RETRYABLE_FAILED or TERMINAL_FAILED)."
- },
- "payoutId": {
- "type": "string",
- "description": "The unique identifier of the seller payout. This identifier is generated once eBay begins processing the payout to the seller's bank account."
- },
- "payoutMemo": {
- "type": "string",
- "description": "This field contains information provided by upstream components, based on internal and external commitments. A typical message would contain the expected arrival time of the payout."
- },
- "payoutInstrument": {
- "description": "This container provides details about the seller's account that received (or is scheduled to receive) the payout. This container is still returned even if the payout failed.",
- "$ref": "#/components/schemas/PayoutInstrument"
- },
- "payoutStatus": {
- "type": "string",
- "description": "This enumeration value indicates the current status of the seller payout. For a successful payout, the value returned will be SUCCEEDED. See the PayoutStatusEnum type for more details on each payout status value. For implementation help, refer to eBay API documentation"
- },
- "payoutStatusDescription": {
- "type": "string",
- "description": "This field provides more details about the current status of payout. The description returned here will correspond with enumeration value returned in the payoutStatus field. The following shows what description text might appear based on the different payoutStatus values:INITIATED: Preparing to sendSUCCEEDED: Funds sentREVERSED: Waiting to retry : Money rejected by seller's bankRETRYABLE_FAILED: Waiting to retryTERMINAL_FAILED: Payout failed
"
- },
- "transactionCount": {
- "type": "integer",
- "description": "This integer value indicates the number of monetary transactions (all orders, refunds, and credits, etc.) that have occurred with the corresponding payout. Its value should always be at least 1, since there is at least one order per seller payout.",
- "format": "int32"
- }
- },
- "description": "This type is used to express the details of one seller payout that is returned with the getPayout or getPayouts methods."
- },
- "PayoutInstrument": {
- "type": "object",
- "properties": {
- "accountLastFourDigits": {
- "type": "string",
- "description": "This string value is the last four digits of the seller's account number."
- },
- "instrumentType": {
- "type": "string",
- "description": "This string value indicates the type of account that received the payout. At this time, seller payouts can only be distributed to bank acounts, so the string value returned in this field will always be BankAccount."
- },
- "nickname": {
- "type": "string",
- "description": "This string value is a seller-provided nickname that the seller uses to represent the bank account."
- }
- },
- "description": "This type provides details about the seller's account that received (or is scheduled to receive) a payout."
- },
- "PayoutSummaryResponse": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "This container shows the total value (and currency type used) of the seller payouts that match the input criteria. This field is not returned if there are no payouts that match the input criteria.",
- "$ref": "#/components/schemas/Amount"
- },
- "payoutCount": {
- "type": "integer",
- "description": "This integer value indicates the total count of payouts to the seller that match the input criteria. This field is always returned, even if there are no payouts that match the input criteria (its value will show 0).",
- "format": "int32"
- },
- "transactionCount": {
- "type": "integer",
- "description": "This integer value indicates the total count of monetary transactions (order payments, buyer refunds, and seller credits) associated with the payouts that match the input criteria. This field is always returned, even if there are no payouts that match the input criteria (its value will show 0). If there is at least one payout that matches the input criteria, the value in this field will be at least 1.",
- "format": "int32"
- }
- },
- "description": "This type is the base response type of the getPayoutSummary method, and contains the total count of seller payouts (that match the input criteria), the total count of monetary transactions (order payment, buyer refunds, or seller credits) associated with those payouts, and the total value of those seller payouts."
- },
- "Payouts": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the getPayouts call request that produced the current page of the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The maximum number of payouts that may be returned per page of the result set. The limit value can be passed in as a query parameter, or if omitted, its value defaults to 20.
Note: If this is the last or only page of the result set, the page may contain fewer payouts than the limit value. To determine the number of pages in a result set, divide the total value (total number of payouts matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total payouts) and the limit value was 50 (show 50 payouts per page), the total number of pages in the result set is three, so the seller would have to make three separate getPayouts calls to view all payouts matching the input criteria.
Maximum: 200
Default: 20",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The getPayouts call URI to use if you wish to view the next page of the result set.
This field is only returned if there is a next page of results to view based on the current input criteria."
- },
- "offset": {
- "type": "integer",
- "description": "This integer value indicates the actual position that the first payout returned on the current page has in the results set. So, if you wanted to view the 11th payout of the result set, you would set the offset value in the request to 10.
In the request, you can use the offset parameter in conjunction with the limit parameter to control the pagination of the output. For example, if offset is set to 30 and limit is set to 10, the call retrieves payouts 31 thru 40 from the resulting collection of payouts.
Note: This feature employs a zero-based list, where the first item in the list has an offset of 0.
Default: 0 (zero)",
- "format": "int32"
- },
- "payouts": {
- "type": "array",
- "description": "An array of one or more payouts that match the input criteria. Details for each payout include the unique identifier of the payout, the status of the payout, the amount of the payout, and the number of monetary transactions associated with the payout.",
- "items": {
- "$ref": "#/components/schemas/Payout"
- }
- },
- "prev": {
- "type": "string",
- "description": "The getPayouts call URI to use if you wish to view the previous page of the result set.
This field is only returned if there is a previous page of results to view based on the current input criteria."
- },
- "total": {
- "type": "integer",
- "description": "This integer value is the total number of payouts in the results set based on the current input criteria. Based on the total number of payouts that match the criteria, and on the limit and offset values, there may be additional pages in the results set.",
- "format": "int32"
- }
- },
- "description": "This type is the base response type of the getPayouts method, and contains an array of one or more payouts (that match the input criteria), the total count of payouts in the response, and various pagination data for the results set."
- },
- "Reference": {
- "type": "object",
- "properties": {
- "referenceId": {
- "type": "string",
- "description": "The identifier of the transaction as specified by the referenceType. For example, with a referenceType of item_id, the referenceId refers to a unique item. This item may have several NON_SALE_CHARGE transactions."
- },
- "referenceType": {
- "type": "string",
- "description": "An enumeration value that identifies the reference type associated with the referenceId. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This field is returned for NON_SALE_CHARGE transactions that contain non-transactional seller fees."
- },
- "SellerFundsSummaryResponse": {
- "type": "object",
- "properties": {
- "availableFunds": {
- "description": "The dollar value in this field represents the total amount of order funds that are available for a payout, but processing for a seller payout has not yet begun. If a seller wants to get more details on sales transactions that have yet to be processed, the seller can use the getTransactions method, and use the transactionStatus filter with its value set to FUNDS_AVAILABLE_FOR_PAYOUT.
This container is not returned if there are no funds available to be processed for a payout.",
- "$ref": "#/components/schemas/Amount"
- },
- "fundsOnHold": {
- "description": "The dollar value in this field represents the total amount of order funds on hold. Seller payment holds can occur for different reasons. If a seller wants to get more details on sales transactions where funds are currently on hold, the seller can use the getTransactions method, and use the transactionStatus filter with its value set to FUNDS_ON_HOLD.
This container is not returned if there are no seller payment holds that will eventually be processed for a payout.",
- "$ref": "#/components/schemas/Amount"
- },
- "processingFunds": {
- "description": "The dollar value in this field represents the total amount of order funds being prepared and processed for a seller payout. If a seller wants to get more details on sales transactions that are being processed, the seller can use the getTransactions method, and use the transactionStatus filter with its value set to FUNDS_PROCESSING.
This container is not returned if there are no funds being processed for a payout.",
- "$ref": "#/components/schemas/Amount"
- },
- "totalFunds": {
- "description": "The dollar value in this field represents the total amount of order funds still due to be distributed to the seller through a seller payout. The dollar value in this field should equal the amounts found in the three other containers.
If there are no pending funds due to the seller through a payout, this container is not returned, and there will not be any response payload at all. Instead, an http status code of 204 - No Content is returned",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type is used by the response payload of the getSellerFundsSummary method. All of the funds returned in getSellerFundsSummary are funds that have not yet been paid to the seller through a seller payout. If there are no funds that are pending, on hold, or being processed for the seller's account, no response payload is returned, and an http status code of 204 - No Content is returned instead."
- },
- "Transaction": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "This container shows the dollar value and currency type of the monetary transaction. This field is always returned even when eBay has yet to initiate a payout for the order.",
- "$ref": "#/components/schemas/Amount"
- },
- "bookingEntry": {
- "type": "string",
- "description": "The enumeration value returned in this field indicates if the monetary transaction amount is a (CREDIT) or a (DEBIT) to the seller's account. Typically, the SALE and CREDIT transaction types are credits to the seller's account, and the REFUND, DISPUTE, SHIPPING_LABEL, and TRANSFER transaction types are debits to the seller's account. For implementation help, refer to eBay API documentation"
- },
- "buyer": {
- "description": "This is the unique eBay user ID for the buyer who purchased the order. This field is not returned for TRANSFER monetary transaction types.",
- "$ref": "#/components/schemas/Buyer"
- },
- "feeType": {
- "type": "string",
- "description": "The type of fee. For implementation help, refer to eBay API documentation"
- },
- "orderId": {
- "type": "string",
- "description": "The unique identifier of the eBay order associated with the monetary transaction."
- },
- "orderLineItems": {
- "type": "array",
- "description": "This array shows the fees that are deducted from a seller payout for each line item in an order.",
- "items": {
- "$ref": "#/components/schemas/OrderLineItem"
- }
- },
- "paymentsEntity": {
- "type": "string",
- "description": "This string value indicates the entity that is processing the payment."
- },
- "payoutId": {
- "type": "string",
- "description": "The unique identifier of the seller payout associated with the monetary transaction. This identifier is generated once eBay begins processing the payout for the corresponding order. This field will not be returned if eBay has not yet begun processing the payout for an order."
- },
- "references": {
- "type": "array",
- "description": "This field contains reference information for the transaction fee. This includes an ID and the type of ID provided (such as item ID).",
- "items": {
- "$ref": "#/components/schemas/Reference"
- }
- },
- "salesRecordReference": {
- "type": "string",
- "description": "The Sales Record Number associated with a sales order. Sales Record Numbers are Selling Manager/Selling Manager Pro identifiers that are created at order checkout.
Note: For all orders originating after February 1, 2020, a value of 0 will be returned in this field. The Sales Record Number field has also been removed from Seller Hub. Instead of salesRecordReference, depend on orderId instead as the identifier of the order. The salesRecordReference field has been scheduled for deprecation, and a date for when this field will no longer be returned at all will be announced soon."
- },
- "totalFeeBasisAmount": {
- "description": "This amount is the total amount of the order before selling fees are deducted from the seller payout associated with the order. To determine the actual amount of the order that will be paid out through a seller payout, deduct the totalFeeAmount from the basePayoutAmount.",
- "$ref": "#/components/schemas/Amount"
- },
- "totalFeeAmount": {
- "description": "This amount is the total amount of selling fees paid for order. A breakdown of fees for each order line item can be found in the orderLineItems array.
This field is even returned if it is 0.0 (no fees deducted from seller payout).",
- "$ref": "#/components/schemas/Amount"
- },
- "transactionDate": {
- "type": "string",
- "description": "This timestamp indicates when the monetary transaction (order purchase, buyer refund, seller credit) occurred. The following (UTC) format is used: YYYY-MM-DDTHH:MM:SS.SSSZ. For example, 2015-08-04T19:09:02.768Z."
- },
- "transactionId": {
- "type": "string",
- "description": "The unique identifier of the monetary transaction. A monetary transaction can be a sales order, an order refund to the buyer, a credit to the seller's account, a debit to the seller for the purchase of a shipping label, or a transaction where eBay recouped money from the seller if the seller lost a buyer-initiated payment dispute."
- },
- "transactionMemo": {
- "type": "string",
- "description": "This field provides more details on shipping label transactions and transactions where the funds are being held by eBay. For shipping label transactions, the transactionMemo gives details about a purchase, a refund, or a price adjustment to the cost of the shipping label. For on-hold transactions, the transactionMemo provides information on the reason for the hold or when the hold will be released (e.g., \"Funds on hold. Estimated release on Jun 1\").
This field is only returned if applicable/available."
- },
- "transactionStatus": {
- "type": "string",
- "description": "This enumeration value indicates the current status of the seller payout associated with the monetary transaction. See the TransactionStatusEnum type for more information on the different states. For implementation help, refer to eBay API documentation"
- },
- "transactionType": {
- "type": "string",
- "description": "This enumeration value indicates whether the monetary transaction is a buyer's payment for an order, a refund to the buyer for a returned item or cancelled order, a credit issued by eBay to the seller's account, a payment dispute between the buyer and seller, or where eBay is billing the seller for an eBay shipping label or another charge (such as a refund to a buyer). Note that the shipping label functionality will initially only be available to a select number of sellers. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used to express the details of one of the following monetary transactions: a buyer's payment for an order, a refund to the buyer for a returned item or cancelled order, or a credit issued by eBay to the seller's account."
- },
- "TransactionSummaryResponse": {
- "type": "object",
- "properties": {
- "adjustmentAmount": {
- "description": "Total adjustment amount for given payee within a specified period.",
- "$ref": "#/components/schemas/Amount"
- },
- "adjustmentBookingEntry": {
- "type": "string",
- "description": "The credit debit sign indicator for adjustment. For implementation help, refer to eBay API documentation"
- },
- "adjustmentCount": {
- "type": "integer",
- "description": "Total adjustment count for given payee within a specified period.",
- "format": "int32"
- },
- "balanceTransferAmount": {
- "description": "The total balance transfer amount for given payee within the specified period.",
- "$ref": "#/components/schemas/Amount"
- },
- "balanceTransferBookingEntry": {
- "type": "string",
- "description": "The credit debit sign indicator for the balance transfer. For implementation help, refer to eBay API documentation"
- },
- "balanceTransferCount": {
- "type": "integer",
- "description": "The total balance transfer count for given payee within the specified period.",
- "format": "int32"
- },
- "creditAmount": {
- "description": "This amount is the total dollar value of all the seller's sales and/or credits that match the input criteria.
Note: Unless the transactionType filter is used in the request to retrieve a specific type of monetary transaction, the creditCount and creditAmount fields account for both order sales and seller credits (the count and value is not distinguished between the two monetary transaction types).
If there are no sales/credits (creditCount=0), this container is not returned.",
- "$ref": "#/components/schemas/Amount"
- },
- "creditBookingEntry": {
- "type": "string",
- "description": "The enumeration value indicates whether the dollar amount in the creditAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be CREDIT. For implementation help, refer to eBay API documentation"
- },
- "creditCount": {
- "type": "integer",
- "description": "This integer value indicates the total number of the seller's sales and/or credits that match the input criteria.
Note: Unless the transactionType filter is used in the request to retrieve a specific type of monetary transaction (sale, buyer refund, or seller credit), the creditCount and creditAmount fields account for both order sales and seller credits (the count and value is not distinguished between the two monetary transaction types).
This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to either REFUND, DISPUTE, or SHIPPING_LABEL.",
- "format": "int32"
- },
- "disputeAmount": {
- "description": "This amount is the total dollar value associated with any existing payment disputes that have been initiated by one or more buyers. Only the orders that match the input criteria are considered. The Payment Disputes methods in the Fulfillment API can be used by the seller to retrieve more information about any payment disputes.
If there are no payment disputes (disputeCount=0), this container is not returned.",
- "$ref": "#/components/schemas/Amount"
- },
- "disputeBookingEntry": {
- "type": "string",
- "description": "The enumeration value indicates whether the dollar amount in the disputeAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT, but its possible that CREDIT could be returned if the seller contested one or more payment disputes and won the dispute. For implementation help, refer to eBay API documentation"
- },
- "disputeCount": {
- "type": "integer",
- "description": "This integer value indicates the total number of payment disputes that have been initiated by one or more buyers. Only the orders that match the input criteria are considered. The Payment Disputes methods in the Fulfillment API can be used by the seller to retrieve more information about any payment disputes.
This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to any value other than DISPUTE.",
- "format": "int32"
- },
- "nonSaleChargeAmount": {
- "description": "The total non-sale charge amount for given payee within a specified period.",
- "$ref": "#/components/schemas/Amount"
- },
- "nonSaleChargeBookingEntry": {
- "type": "string",
- "description": "The credit/debit sign indicator for the non-sale charge. For implementation help, refer to eBay API documentation"
- },
- "nonSaleChargeCount": {
- "type": "integer",
- "description": "The total non-sale charge count for given payee within a specified period.",
- "format": "int32"
- },
- "onHoldAmount": {
- "description": "This amount is the total dollar value of order sales where the associated funds are on hold. Only the orders that match the input criteria are considered.
If there are no seller payment holds (onHoldCount=0), this container is not returned.",
- "$ref": "#/components/schemas/Amount"
- },
- "onHoldBookingEntry": {
- "type": "string",
- "description": "The enumeration value indicates whether the dollar amount in the onHoldAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be CREDIT, since on-hold funds should eventually be released as part of a payout to the seller once the hold is cleared. For implementation help, refer to eBay API documentation"
- },
- "onHoldCount": {
- "type": "integer",
- "description": "This integer value indicates the total number of order sales where the associated funds are on hold. Only the orders that match the input criteria are considered.
This field is generally returned, even if 0, but it will not be returned if a transactionStatus filter is used, and its value is set to any value other than FUNDS_ON_HOLD.",
- "format": "int32"
- },
- "refundAmount": {
- "description": "This amount is the total dollar value of buyer refunds that match the input criteria.
If there are no refunds (refundCount=0), this container is not returned.",
- "$ref": "#/components/schemas/Amount"
- },
- "refundBookingEntry": {
- "type": "string",
- "description": "The enumeration value indicates whether the dollar amount in the refundAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT since this a refund from the seller to the buyer. For implementation help, refer to eBay API documentation"
- },
- "refundCount": {
- "type": "integer",
- "description": "This integer value indicates the total number of buyer refunds that match the input criteria.
This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to any value other than REFUND.",
- "format": "int32"
- },
- "shippingLabelAmount": {
- "description": "This is the total dollar value of the eBay shipping labels purchased by the seller.",
- "$ref": "#/components/schemas/Amount"
- },
- "shippingLabelBookingEntry": {
- "type": "string",
- "description": "The enumeration value indicates whether the dollar amount in the shippingLabelAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT, as eBay will charge the seller when eBay shipping labels are purchased, but it can be CREDIT if the seller was refunded for a shipping label or was possibly overcharged for a shipping label. For implementation help, refer to eBay API documentation"
- },
- "shippingLabelCount": {
- "type": "integer",
- "description": "This is the total number of eBay shipping labels purchased by the seller. The count returned here may depend on the specified input criteria.",
- "format": "int32"
- },
- "transferAmount": {
- "description": "This amount is the total dollar value of buyer refund transfers that match the input criteria.
If there are no transfers (refundCount=0), this container is not returned.",
- "$ref": "#/components/schemas/Amount"
- },
- "transferBookingEntry": {
- "type": "string",
- "description": "The enumeration value indicates whether the dollar amount in the transferAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT since this a seller reimbursement to eBay for buyer refunds. For implementation help, refer to eBay API documentation"
- },
- "transferCount": {
- "type": "integer",
- "description": "This integer value indicates the total number of buyer refund transfers that match the input criteria.
This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to any value other than TRANSFER.",
- "format": "int32"
- }
- },
- "description": "This type is the base response type of the getTransactionSummary method, and based on the filters that are used in the getTransactionSummary call URI, the response may include total count and amount of the seller's sales and credits, total count and amount of buyer refunds, and total count and amount of seller payment holds."
- },
- "Transactions": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the getTransactions method request that produced the current page of the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The maximum number of monetary transactions that may be returned per page of the result set. The limit value can be passed in as a query parameter, or if omitted, its value defaults to 20.
Note: If this is the last or only page of the result set, the page may contain fewer monetary transactions than the limit value. To determine the number of pages in a result set, divide the total value (total number of monetary transactions matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total monetary transactions) and the limit value was 50 (show 50 monetary transactions per page), the total number of pages in the result set is three, so the seller would have to make three separate getTransactions calls to view all monetary transactions matching the input criteria.
Maximum: 200
Default: 20",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The getTransactions method URI to use if you wish to view the next page of the result set.
This field is only returned if there is a next page of results to view based on the current input criteria."
- },
- "offset": {
- "type": "integer",
- "description": "This integer value indicates the actual position that the first monetary transaction returned on the current page has in the results set. So, if you wanted to view the 11th monetary transaction of the result set, you would set the offset value in the request to 10.
In the request, you can use the offset parameter in conjunction with the limit parameter to control the pagination of the output. For example, if offset is set to 30 and limit is set to 10, the method retrieves monetary transactions 31 thru 40 from the resulting collection of monetary transactions.
Note: This feature employs a zero-based list, where the first item in the list has an offset of 0.
Default: 0 (zero)",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The getTransactions method URI to use if you wish to view the previous page of the result set.
This field is only returned if there is a previous page of results to view based on the current input criteria."
- },
- "total": {
- "type": "integer",
- "description": "This integer value is the total amount of monetary transactions in the result set based on the current input criteria. Based on the total number of monetary transactions that match the criteria, and on the limit and offset values, there may be additional pages in the results set.",
- "format": "int32"
- },
- "transactions": {
- "type": "array",
- "description": "An array of one or more monetary transactions that match the input criteria. Details for each monetary transaction may include the unique identifier of the order associated with the monetary transaction, the status of the transaction, the amount of the order, the order's buyer, and the unique identifier of the payout (if a payout has been initiated/issued for the order).",
- "items": {
- "$ref": "#/components/schemas/Transaction"
- }
- }
- },
- "description": "This is the base response type of the getTransactions method. The getTransactions response includes details on one or more monetary transactions that match the input criteria, as well as pagination data. "
- },
- "Transfer": {
- "type": "object",
- "properties": {
- "fundingSource": {
- "description": "This container provides details about the seller's funding source to reimburse eBay for the transfer, such as a bank account, a credit card, or available seller payout funds.",
- "$ref": "#/components/schemas/FundingSource"
- },
- "transactionDate": {
- "type": "string",
- "description": "This timestamp indicates the date/time of the transfer. The following (UTC) format is used: YYYY-MM-DDTHH:MM:SS.SSSZ. For example, 2020-08-04T19:09:02.768Z"
- },
- "transferAmount": {
- "description": "The amount of the transfer being deducted from the funding source.",
- "$ref": "#/components/schemas/Amount"
- },
- "transferDetail": {
- "description": "This container provides more details about the transfer, including details on the charge(s) associated with the transfer. Multiple charges can be addressed with one transfer.",
- "$ref": "#/components/schemas/TransferDetail"
- },
- "transferId": {
- "type": "string",
- "description": "The unique identifier of the TRANSFER transaction type. This is the same value that was passed into the end of the call URI."
- }
- },
- "description": "This type is the base response type used by TRANSFER transaction type that is returned in the response."
- },
- "TransferDetail": {
- "type": "object",
- "properties": {
- "balanceAdjustment": {
- "description": "This container shows the seller payout balance that will be applied toward the charges outlined in the charges array.",
- "$ref": "#/components/schemas/BalanceAdjustment"
- },
- "charges": {
- "type": "array",
- "description": "This container is an array of one or more charges related to the transfer. Charges can be related to an order cancellation, order return, case, payment dispute, etc.",
- "items": {
- "$ref": "#/components/schemas/Charge"
- }
- },
- "totalChargeNetAmount": {
- "description": "This container shows the total amount that the seller owes for all of the charges outlined in the charges array.",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type is used by the transferDetail container, which provides more details about the transfer and the charge(s) associated with the transfer."
- }
- },
- "securitySchemes": {
- "api_auth": {
- "type": "oauth2",
- "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
- "flows": {
- "authorizationCode": {
- "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
- "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
- "scopes": {
- "https://api.ebay.com/oauth/api_scope/sell.finances": "View and manage your payment and order information to display this information to you and allow you to initiate refunds using the third party application"
}
- }
}
- }
}
- }
}
\ No newline at end of file
diff --git a/specs/sell_fulfillment_v1_oas3.json b/specs/sell_fulfillment_v1_oas3.json
index eec1f1f8..cd4e3cda 100644
--- a/specs/sell_fulfillment_v1_oas3.json
+++ b/specs/sell_fulfillment_v1_oas3.json
@@ -1,3817 +1,3817 @@
{
- "openapi": "3.0.0",
- "info": {
- "title": "Fulfillment API",
- "description": "Use the Fulfillment API to complete the process of packaging, addressing, handling, and shipping each order on behalf of the seller, in accordance with the payment method and timing specified at checkout.",
- "contact": {
- "name": "eBay Inc."
+ "openapi": "3.0.0",
+ "info": {
+ "title": "Fulfillment API",
+ "description": "Use the Fulfillment API to complete the process of packaging, addressing, handling, and shipping each order on behalf of the seller, in accordance with the payment method and timing specified at checkout.",
+ "contact": {
+ "name": "eBay Inc."
+ },
+ "license": {
+ "name": "eBay API License Agreement",
+ "url": "https://developer.ebay.com/join/api-license-agreement"
+ },
+ "version": "v1.20.7"
},
- "license": {
- "name": "eBay API License Agreement",
- "url": "https://developer.ebay.com/join/api-license-agreement"
- },
- "version": "v1.20.7"
- },
- "servers": [
- {
- "url": "https://api.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/fulfillment/v1"
- }
- }
- },
- {
- "url": "https://apiz.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/fulfillment/v1"
- }
- }
- }
- ],
- "paths": {
- "/order/{orderId}": {
- "get": {
- "tags": [
- "order"
- ],
- "description": "Use this call to retrieve the contents of an order based on its unique identifier, orderId. This value was returned in the getOrders call's orders.orderId field when you searched for orders by creation date, modification date, or fulfillment status. Include the optional fieldGroups query parameter set to TAX_BREAKDOWN to return a breakdown of the taxes and fees.
The returned Order object contains information you can use to create and process fulfillments, including: - Information about the buyer and seller
- Information about the order's line items
- The plans for packaging, addressing and shipping the order
- The status of payment, packaging, addressing, and shipping the order
- A summary of monetary amounts specific to the order such as pricing, payments, and shipping costs
- A summary of applied taxes and fees, and optionally a breakdown of each
",
- "operationId": "getOrder",
- "parameters": [
- {
- "name": "fieldGroups",
- "in": "query",
- "description": "This parameter lets you control what is returned in the response.
Note: The only presently supported value is TAX_BREAKDOWN. This field group adds addition fields to the response that return a breakdown of taxes and fees.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "orderId",
- "in": "path",
- "description": "This path parameter is used to specify the unique identifier of the order being retrieved.
Use the getOrders method to retrieve order IDs. Order ID values are also shown in My eBay/Seller Hub.
Note: getOrders can return orders up to two years old. Do not provide the orderId for an order created more than two years in the past.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Order"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "32100": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid order ID: {orderId}"
- },
- "32800": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid field group: {fieldGroup}"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "30500": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "System error"
+ "servers": [
+ {
+ "url": "https://api.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/fulfillment/v1"
}
- }
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment",
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly"
- ]
- }
- ]
- }
- },
- "/order": {
- "get": {
- "tags": [
- "order"
- ],
- "description": "Use this method to search for and retrieve one or more orders based on their creation date, last modification date, or fulfillment status using the filter parameter. You can alternatively specify a list of orders using the orderIds parameter. Include the optional fieldGroups query parameter set to TAX_BREAKDOWN to return a breakdown of the taxes and fees. By default, when no filters are used this call returns all orders created within the last 90 days.
The returned Order objects contain information you can use to create and process fulfillments, including: - Information about the buyer and seller
- Information about the order's line items
- The plans for packaging, addressing and shipping the order
- The status of payment, packaging, addressing, and shipping the order
- A summary of monetary amounts specific to the order such as pricing, payments, and shipping costs
- A summary of applied taxes and fees, and optionally a breakdown of each
Important: In this call, the cancelStatus.cancelRequests array is returned but is always empty. Use the getOrder call instead, which returns this array fully populated with information about any cancellation requests.",
- "operationId": "getOrders",
- "parameters": [
- {
- "name": "fieldGroups",
- "in": "query",
- "description": "This parameter lets you control what is returned in the response.
Note: The only presently supported value is TAX_BREAKDOWN. This field group adds addition fields to the response that return a breakdown of taxes and fees.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "filter",
- "in": "query",
- "description": "One or more comma-separated criteria for narrowing down the collection of orders returned by this call. These criteria correspond to specific fields in the response payload. Multiple filter criteria combine to further restrict the results.
Note: getOrders can return orders up to two years old. Do not set the creationdate filter to a date beyond two years in the past.
Note: If the orderIds parameter is included in the request, the filter parameter will be ignored.
The available criteria are as follows: creationdate- The time period during which qualifying orders were created (the orders.creationDate field). In the URI, this is expressed as a starting timestamp, with or without an ending timestamp (in brackets). The timestamps are in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.For example:
creationdate:[2016-02-21T08:25:43.511Z..] identifies orders created on or after the given timestamp.creationdate:[2016-02-21T08:25:43.511Z..2016-04-21T08:25:43.511Z] identifies orders created between the given timestamps, inclusive.
lastmodifieddate- The time period during which qualifying orders were last modified (the orders.modifiedDate field). In the URI, this is expressed as a starting timestamp, with or without an ending timestamp (in brackets). The timestamps are in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.For example:
lastmodifieddate:[2016-05-15T08:25:43.511Z..] identifies orders modified on or after the given timestamp.lastmodifieddate:[2016-05-15T08:25:43.511Z..2016-05-31T08:25:43.511Z] identifies orders modified between the given timestamps, inclusive.
Note: If creationdate and lastmodifieddate are both included, only creationdate is used.
orderfulfillmentstatus- The degree to which qualifying orders have been shipped (the orders.orderFulfillmentStatus field). In the URI, this is expressed as one of the following value combinations:
orderfulfillmentstatus:{NOT_STARTED|IN_PROGRESS} specifies orders for which no shipping fulfillments have been started, plus orders for which at least one shipping fulfillment has been started but not completed.orderfulfillmentstatus:{FULFILLED|IN_PROGRESS} specifies orders for which all shipping fulfillments have been completed, plus orders for which at least one shipping fulfillment has been started but not completed.
Note: The values NOT_STARTED, IN_PROGRESS, and FULFILLED can be used in various combinations, but only the combinations shown here are currently supported.
Here is an example of a getOrders call using all of these filters:
GET https://api.ebay.com/sell/v1/order?
filter=creationdate:%5B2016-03-21T08:25:43.511Z..2016-04-21T08:25:43.511Z%5D,
lastmodifieddate:%5B2016-05-15T08:25:43.511Z..%5D,
orderfulfillmentstatus:%7BNOT_STARTED%7CIN_PROGRESS%7D
Note: This call requires that certain special characters in the URI query string be percent-encoded:
[ = %5B ] = %5D { = %7B | = %7C } = %7D
This query filter example uses these codes. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/fulfillment/types/api:FilterField",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "limit",
- "in": "query",
- "description": "The number of orders to return per page of the result set. Use this parameter in conjunction with the offset parameter to control the pagination of the output.
For example, if offset is set to 10 and limit is set to 10, the call retrieves orders 11 thru 20 from the result set.
If a limit is not set, the limit defaults to 50 and returns up to 50 orders. If a requested limit is more than 200, the call fails and returns an error.
Note: This feature employs a zero-based list, where the first item in the list has an offset of 0. If the orderIds parameter is included in the request, this parameter will be ignored.
Maximum: 200
Default: 50",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "Specifies the number of orders to skip in the result set before returning the first order in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "orderIds",
- "in": "query",
- "description": "A comma-separated list of the unique identifiers of the orders to retrieve (maximum 50). If one or more order ID values are specified through the orderIds query parameter, all other query parameters will be ignored.
Note: getOrders can return orders up to two years old. Do not provide the orderId for an order created more than two years in the past.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/OrderSearchPagedCollection"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "30700": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid filter name: {fieldname}"
- },
- "30800": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid filter value {fieldvalue} for filter {fieldname}"
- },
- "30810": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid date format"
- },
- "30820": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Start date is missing"
- },
- "30830": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Time range between start date and end date must be within '{allowedTime}' years."
- },
- "30840": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Start date should be before end date"
- },
- "30850": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Start and end dates can't be in the future"
- },
- "30900": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Exceeded maximum number of order IDs (the current limit is 50)"
- },
- "31000": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid offset: {offsetvalue}"
- },
- "31100": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid limit: {limitvalue}"
- },
- "32800": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid field group: {fieldGroup}"
+ {
+ "url": "https://apiz.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/fulfillment/v1"
}
- }
}
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "30500": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "System error"
+ }
+ ],
+ "paths": {
+ "/order/{orderId}": {
+ "get": {
+ "tags": [
+ "order"
+ ],
+ "description": "Use this call to retrieve the contents of an order based on its unique identifier, orderId. This value was returned in the getOrders call's orders.orderId field when you searched for orders by creation date, modification date, or fulfillment status. Include the optional fieldGroups query parameter set to TAX_BREAKDOWN to return a breakdown of the taxes and fees.
The returned Order object contains information you can use to create and process fulfillments, including: - Information about the buyer and seller
- Information about the order's line items
- The plans for packaging, addressing and shipping the order
- The status of payment, packaging, addressing, and shipping the order
- A summary of monetary amounts specific to the order such as pricing, payments, and shipping costs
- A summary of applied taxes and fees, and optionally a breakdown of each
",
+ "operationId": "getOrder",
+ "parameters": [
+ {
+ "name": "fieldGroups",
+ "in": "query",
+ "description": "This parameter lets you control what is returned in the response.
Note: The only presently supported value is TAX_BREAKDOWN. This field group adds addition fields to the response that return a breakdown of taxes and fees.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "orderId",
+ "in": "path",
+ "description": "This path parameter is used to specify the unique identifier of the order being retrieved.
Use the getOrders method to retrieve order IDs. Order ID values are also shown in My eBay/Seller Hub.
Note: getOrders can return orders up to two years old. Do not provide the orderId for an order created more than two years in the past.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Order"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "32100": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid order ID: {orderId}"
+ },
+ "32800": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid field group: {fieldGroup}"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "30500": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "System error"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment",
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly"
+ ]
+ }
+ ]
+ }
+ },
+ "/order": {
+ "get": {
+ "tags": [
+ "order"
+ ],
+ "description": "Use this method to search for and retrieve one or more orders based on their creation date, last modification date, or fulfillment status using the filter parameter. You can alternatively specify a list of orders using the orderIds parameter. Include the optional fieldGroups query parameter set to TAX_BREAKDOWN to return a breakdown of the taxes and fees. By default, when no filters are used this call returns all orders created within the last 90 days.
The returned Order objects contain information you can use to create and process fulfillments, including: - Information about the buyer and seller
- Information about the order's line items
- The plans for packaging, addressing and shipping the order
- The status of payment, packaging, addressing, and shipping the order
- A summary of monetary amounts specific to the order such as pricing, payments, and shipping costs
- A summary of applied taxes and fees, and optionally a breakdown of each
Important: In this call, the cancelStatus.cancelRequests array is returned but is always empty. Use the getOrder call instead, which returns this array fully populated with information about any cancellation requests.",
+ "operationId": "getOrders",
+ "parameters": [
+ {
+ "name": "fieldGroups",
+ "in": "query",
+ "description": "This parameter lets you control what is returned in the response.
Note: The only presently supported value is TAX_BREAKDOWN. This field group adds addition fields to the response that return a breakdown of taxes and fees.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "One or more comma-separated criteria for narrowing down the collection of orders returned by this call. These criteria correspond to specific fields in the response payload. Multiple filter criteria combine to further restrict the results.
Note: getOrders can return orders up to two years old. Do not set the creationdate filter to a date beyond two years in the past.
Note: If the orderIds parameter is included in the request, the filter parameter will be ignored.
The available criteria are as follows: creationdate- The time period during which qualifying orders were created (the orders.creationDate field). In the URI, this is expressed as a starting timestamp, with or without an ending timestamp (in brackets). The timestamps are in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.For example:
creationdate:[2016-02-21T08:25:43.511Z..] identifies orders created on or after the given timestamp.creationdate:[2016-02-21T08:25:43.511Z..2016-04-21T08:25:43.511Z] identifies orders created between the given timestamps, inclusive.
lastmodifieddate- The time period during which qualifying orders were last modified (the orders.modifiedDate field). In the URI, this is expressed as a starting timestamp, with or without an ending timestamp (in brackets). The timestamps are in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.For example:
lastmodifieddate:[2016-05-15T08:25:43.511Z..] identifies orders modified on or after the given timestamp.lastmodifieddate:[2016-05-15T08:25:43.511Z..2016-05-31T08:25:43.511Z] identifies orders modified between the given timestamps, inclusive.
Note: If creationdate and lastmodifieddate are both included, only creationdate is used.
orderfulfillmentstatus- The degree to which qualifying orders have been shipped (the orders.orderFulfillmentStatus field). In the URI, this is expressed as one of the following value combinations:
orderfulfillmentstatus:{NOT_STARTED|IN_PROGRESS} specifies orders for which no shipping fulfillments have been started, plus orders for which at least one shipping fulfillment has been started but not completed.orderfulfillmentstatus:{FULFILLED|IN_PROGRESS} specifies orders for which all shipping fulfillments have been completed, plus orders for which at least one shipping fulfillment has been started but not completed.
Note: The values NOT_STARTED, IN_PROGRESS, and FULFILLED can be used in various combinations, but only the combinations shown here are currently supported.
Here is an example of a getOrders call using all of these filters:
GET https://api.ebay.com/sell/v1/order?
filter=creationdate:%5B2016-03-21T08:25:43.511Z..2016-04-21T08:25:43.511Z%5D,
lastmodifieddate:%5B2016-05-15T08:25:43.511Z..%5D,
orderfulfillmentstatus:%7BNOT_STARTED%7CIN_PROGRESS%7D
Note: This call requires that certain special characters in the URI query string be percent-encoded:
[ = %5B ] = %5D { = %7B | = %7C } = %7D
This query filter example uses these codes. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/fulfillment/types/api:FilterField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The number of orders to return per page of the result set. Use this parameter in conjunction with the offset parameter to control the pagination of the output.
For example, if offset is set to 10 and limit is set to 10, the call retrieves orders 11 thru 20 from the result set.
If a limit is not set, the limit defaults to 50 and returns up to 50 orders. If a requested limit is more than 200, the call fails and returns an error.
Note: This feature employs a zero-based list, where the first item in the list has an offset of 0. If the orderIds parameter is included in the request, this parameter will be ignored.
Maximum: 200
Default: 50",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "Specifies the number of orders to skip in the result set before returning the first order in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "orderIds",
+ "in": "query",
+ "description": "A comma-separated list of the unique identifiers of the orders to retrieve (maximum 50). If one or more order ID values are specified through the orderIds query parameter, all other query parameters will be ignored.
Note: getOrders can return orders up to two years old. Do not provide the orderId for an order created more than two years in the past.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/OrderSearchPagedCollection"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "30700": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid filter name: {fieldname}"
+ },
+ "30800": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid filter value {fieldvalue} for filter {fieldname}"
+ },
+ "30810": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid date format"
+ },
+ "30820": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Start date is missing"
+ },
+ "30830": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Time range between start date and end date must be within '{allowedTime}' years."
+ },
+ "30840": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Start date should be before end date"
+ },
+ "30850": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Start and end dates can't be in the future"
+ },
+ "30900": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Exceeded maximum number of order IDs (the current limit is 50)"
+ },
+ "31000": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid offset: {offsetvalue}"
+ },
+ "31100": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid limit: {limitvalue}"
+ },
+ "32800": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid field group: {fieldGroup}"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "30500": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "System error"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment",
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly"
+ ]
+ }
+ ]
+ }
+ },
+ "/order/{order_id}/issue_refund": {
+ "post": {
+ "tags": [
+ "order"
+ ],
+ "summary": "Issue Refund",
+ "description": "Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including issueRefund. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
This method allows a seller to issue a full or partial refund to a buyer for an order. Full or partial refunds can be issued at the order level or line item level.
The refunds issued through this method are processed asynchronously, so the refund will not show as 'Refunded' right away. A seller will have to make a subsequent getOrder call to check the status of the refund. The status of an order refund can be found in the paymentSummary.refunds.refundStatus field of the getOrder response.",
+ "operationId": "issueRefund",
+ "parameters": [
+ {
+ "name": "order_id",
+ "in": "path",
+ "description": "This path parameter is used to specify the unique identifier of the order associated with a refund.
Use the getOrders method to retrieve order IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/IssueRefundRequest"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Refund"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "34901": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Order id can't be null or empty."
+ },
+ "34902": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Request can't be empty."
+ },
+ "34903": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "The refund reason must be specified."
+ },
+ "34905": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Either orderLevelRefundAmount or refundItems must be specified."
+ },
+ "34906": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "The amount value must be specified."
+ },
+ "34907": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "The amount value must be positive and within two decimals."
+ },
+ "34908": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "The amount currency must be specified."
+ },
+ "34909": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "The amount currency isn't correct."
+ },
+ "34910": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Either legacyReference or lineItemId must be specified for item level refund."
+ },
+ "34911": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Legacy item id must be specified for item level refund if you use legacyReference."
+ },
+ "34912": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Legacy transaction id must be specified for item level refund if you use legacyReference."
+ },
+ "34914": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Can't find the item in the order."
+ },
+ "34915": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "The refund amount exceeds order amount."
+ },
+ "34916": {
+ "domain": "API_FULFILLMENT",
+ "category": "BUSINESS",
+ "description": "A post-transaction case exists on this order, seller refund can't be triggered."
+ },
+ "34917": {
+ "domain": "API_FULFILLMENT",
+ "category": "BUSINESS",
+ "description": "This order was already refunded."
+ },
+ "34920": {
+ "domain": "API_FULFILLMENT",
+ "category": "BUSINESS",
+ "description": "It's too late to issue a refund for this order."
+ },
+ "34921": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "The comment exceeds the length limit, please make sure it doesn't exceed 1000 characters."
+ },
+ "34922": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Refund can't be issued while previous refund is processing."
+ },
+ "34923": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Refund cannot be issued for this type of order."
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Access Forbidden"
+ },
+ "404": {
+ "description": "Resource Not found",
+ "x-response-codes": {
+ "errors": {
+ "34913": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Can not find the order."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "x-response-codes": {
+ "errors": {
+ "34918": {
+ "domain": "API_FULFILLMENT",
+ "category": "BUSINESS",
+ "description": "This is not an eBay managed payments order."
+ },
+ "34919": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Unauthorized access."
+ },
+ "34924": {
+ "domain": "API_FULFILLMENT",
+ "category": "BUSINESS",
+ "description": "The item refund amount exceeds the item remaining amount."
+ },
+ "34925": {
+ "domain": "API_FULFILLMENT",
+ "category": "BUSINESS",
+ "description": "The refund operation could not be completed with any of the payment methods saved to the seller's account."
+ },
+ "34926": {
+ "domain": "API_FULFILLMENT",
+ "category": "BUSINESS",
+ "description": "A suitable payment method could not be found for the refund operation. Please resolve in Seller Hub."
+ },
+ "34927": {
+ "domain": "API_FULFILLMENT",
+ "category": "BUSINESS",
+ "description": "The selected payment method for the refund operation was invalid or declined."
+ },
+ "34928": {
+ "domain": "API_FULFILLMENT",
+ "category": "BUSINESS",
+ "description": "Your refund did not go through because we could not verify your payment option. Please change your payment option and try again."
+ },
+ "34929": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "You cannot refund this order yet since the buyer payment has not been processed. Please try again later."
+ },
+ "34930": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Default payment method limit exceeded. Please use a different payment option or try again later."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "34900": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.finances"
+ ]
+ }
+ ]
+ }
+ },
+ "/order/{orderId}/shipping_fulfillment": {
+ "get": {
+ "tags": [
+ "shipping_fulfillment"
+ ],
+ "description": "Use this call to retrieve the contents of all fulfillments currently defined for a specified order based on the order's unique identifier, orderId. This value is returned in the getOrders call's members.orderId field when you search for orders by creation date or shipment status.",
+ "operationId": "getShippingFulfillments",
+ "parameters": [
+ {
+ "name": "orderId",
+ "in": "path",
+ "description": "This path parameter is used to specify the unique identifier of the order associated with the shipping fulfillments being retrieved.
Use the getOrders method to retrieve order IDs. Order ID values are also shown in My eBay/Seller Hub.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ShippingFulfillmentPagedCollection"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "32100": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid order ID: {orderId}"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "30500": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "System error"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment",
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly"
+ ]
+ }
+ ]
+ },
+ "post": {
+ "tags": [
+ "shipping_fulfillment"
+ ],
+ "description": "When you group an order's line items into one or more packages, each package requires a corresponding plan for handling, addressing, and shipping; this is a shipping fulfillment. For each package, execute this call once to generate a shipping fulfillment associated with that package.
Note: A single line item in an order can consist of multiple units of a purchased item, and one unit can consist of multiple parts or components. Although these components might be provided by the manufacturer in separate packaging, the seller must include all components of a given line item in the same package.
Before using this call for a given package, you must determine which line items are in the package. If the package has been shipped, you should provide the date of shipment in the request. If not provided, it will default to the current date and time.",
+ "operationId": "createShippingFulfillment",
+ "parameters": [
+ {
+ "name": "orderId",
+ "in": "path",
+ "description": "This path parameter is used to specify the unique identifier of the order associated with the shipping fulfillment being created.
Use the getOrders method to retrieve order IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "fulfillment payload",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "fulfillment payload",
+ "$ref": "#/components/schemas/ShippingFulfillmentDetails"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "201": {
+ "description": "Created. The call also returns the following location response header:
{ENV}/sell/fulfillment/v1/order/{ORDERID}/shipping_fulfillment/{FULFILLMENTID}
The ENV string is the HTTPS path to the same eBay supported environment in which this call was issued. The ORDERID parameter is the unique identifier of the order addressed by this call; for example, 01-03955-36441. The FULFILLMENTID parameter identifies the newly created fulfillment; for example, 9405509699937003457459. Use this Get Fulfillment URI to retrieve the contents of the new fulfillment.",
+ "headers": {
+ "Location": {
+ "schema": {
+ "type": "string",
+ "description": "The location response header contains the getShippingFulfillment URI to retrieve the contents of the newly created shipping fulfillment. The URL includes the eBay-assigned fulfillmentId, which you can use to reference the shipping fulfillment."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "32100": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid Order Id: {orderId}"
+ },
+ "32200": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid line item id: {lineItemId}"
+ },
+ "32210": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Duplicate line item in the request"
+ },
+ "32300": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid shipment tracking number or carrier"
+ },
+ "32400": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Requested user is suspended"
+ },
+ "32500": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid shipped date"
+ },
+ "32600": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid input data"
+ },
+ "34100": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Maximum tracking number for order is exceeded"
+ },
+ "34200": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Line Items contain Global Shipping Program and non-Global Shipping Program orders"
+ },
+ "34300": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Mark As Shipped for multiple Global Shipping Program line items is not supported"
+ },
+ "34500": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Please use PUT operation for updating shipping fulfillment"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "30500": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "System error"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment"
+ ]
+ }
+ ]
+ }
+ },
+ "/order/{orderId}/shipping_fulfillment/{fulfillmentId}": {
+ "get": {
+ "tags": [
+ "shipping_fulfillment"
+ ],
+ "description": "Use this call to retrieve the contents of a fulfillment based on its unique identifier, fulfillmentId (combined with the associated order's orderId). The fulfillmentId value was originally generated by the createShippingFulfillment call, and is returned by the getShippingFulfillments call in the members.fulfillmentId field.",
+ "operationId": "getShippingFulfillment",
+ "parameters": [
+ {
+ "name": "fulfillmentId",
+ "in": "path",
+ "description": "This path parameter is used to specify the unique identifier of the shipping fulfillment being retrieved.
Use the getShippingFulfillments method to retrieved fulfillment IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "orderId",
+ "in": "path",
+ "description": "This path parameter is used to specify the unique identifier of the order associated with the shipping fulfillment being retrieved.
Use the getOrders method to retrieve order IDs. Order ID values are also shown in My eBay/Seller Hub.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ShippingFulfillment"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "32100": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid order ID: {orderId}"
+ },
+ "32110": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid shipping fulfillment ID: {fulfillmentId}"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "30500": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "System error"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment",
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly"
+ ]
+ }
+ ]
+ }
+ },
+ "/payment_dispute/{payment_dispute_id}": {
+ "get": {
+ "tags": [
+ "payment_dispute"
+ ],
+ "summary": "Get Payment Dispute Details",
+ "description": "This method retrieves detailed information on a specific payment dispute. The payment dispute identifier is passed in as path parameter at the end of the call URI.
Below is a summary of the information that is retrieved:- Current status of payment dispute
- Amount of the payment dispute
- Reason the payment dispute was opened
- Order and line items associated with the payment dispute
- Seller response options if an action is currently required on the payment dispute
- Details on the results of the payment dispute if it has been closed
- Details on any evidence that was provided by the seller to fight the payment dispute
",
+ "operationId": "getPaymentDispute",
+ "parameters": [
+ {
+ "name": "payment_dispute_id",
+ "in": "path",
+ "description": "This parameter is used to specify the unique identifier of the payment dispute being retrieved.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PaymentDispute"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request"
+ },
+ "404": {
+ "description": "Invalid Payment Dispute Id",
+ "x-response-codes": {
+ "errors": {
+ "33001": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid Payment Dispute Id"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "33000": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
+ ]
+ }
+ ]
+ },
+ "servers": [
+ {
+ "url": "https://apiz.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/fulfillment/v1"
+ }
+ }
}
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment",
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly"
]
- }
- ]
- }
- },
- "/order/{order_id}/issue_refund": {
- "post": {
- "tags": [
- "order"
- ],
- "summary": "Issue Refund",
- "description": "Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including issueRefund. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
This method allows a seller to issue a full or partial refund to a buyer for an order. Full or partial refunds can be issued at the order level or line item level.
The refunds issued through this method are processed asynchronously, so the refund will not show as 'Refunded' right away. A seller will have to make a subsequent getOrder call to check the status of the refund. The status of an order refund can be found in the paymentSummary.refunds.refundStatus field of the getOrder response.",
- "operationId": "issueRefund",
- "parameters": [
- {
- "name": "order_id",
- "in": "path",
- "description": "This path parameter is used to specify the unique identifier of the order associated with a refund.
Use the getOrders method to retrieve order IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/IssueRefundRequest"
- }
- }
- },
- "required": false
},
- "responses": {
- "200": {
- "description": "OK",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Refund"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "34901": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Order id can't be null or empty."
- },
- "34902": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Request can't be empty."
- },
- "34903": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "The refund reason must be specified."
- },
- "34905": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Either orderLevelRefundAmount or refundItems must be specified."
- },
- "34906": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "The amount value must be specified."
- },
- "34907": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "The amount value must be positive and within two decimals."
- },
- "34908": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "The amount currency must be specified."
- },
- "34909": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "The amount currency isn't correct."
- },
- "34910": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Either legacyReference or lineItemId must be specified for item level refund."
- },
- "34911": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Legacy item id must be specified for item level refund if you use legacyReference."
- },
- "34912": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Legacy transaction id must be specified for item level refund if you use legacyReference."
- },
- "34914": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Can't find the item in the order."
- },
- "34915": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "The refund amount exceeds order amount."
- },
- "34916": {
- "domain": "API_FULFILLMENT",
- "category": "BUSINESS",
- "description": "A post-transaction case exists on this order, seller refund can't be triggered."
- },
- "34917": {
- "domain": "API_FULFILLMENT",
- "category": "BUSINESS",
- "description": "This order was already refunded."
- },
- "34920": {
- "domain": "API_FULFILLMENT",
- "category": "BUSINESS",
- "description": "It's too late to issue a refund for this order."
- },
- "34921": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "The comment exceeds the length limit, please make sure it doesn't exceed 1000 characters."
- },
- "34922": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Refund can't be issued while previous refund is processing."
- },
- "34923": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Refund cannot be issued for this type of order."
- }
- }
- }
- },
- "403": {
- "description": "Access Forbidden"
- },
- "404": {
- "description": "Resource Not found",
- "x-response-codes": {
- "errors": {
- "34913": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Can not find the order."
- }
- }
- }
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "34918": {
- "domain": "API_FULFILLMENT",
- "category": "BUSINESS",
- "description": "This is not an eBay managed payments order."
- },
- "34919": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Unauthorized access."
- },
- "34924": {
- "domain": "API_FULFILLMENT",
- "category": "BUSINESS",
- "description": "The item refund amount exceeds the item remaining amount."
- },
- "34925": {
- "domain": "API_FULFILLMENT",
- "category": "BUSINESS",
- "description": "The refund operation could not be completed with any of the payment methods saved to the seller's account."
- },
- "34926": {
- "domain": "API_FULFILLMENT",
- "category": "BUSINESS",
- "description": "A suitable payment method could not be found for the refund operation. Please resolve in Seller Hub."
- },
- "34927": {
- "domain": "API_FULFILLMENT",
- "category": "BUSINESS",
- "description": "The selected payment method for the refund operation was invalid or declined."
- },
- "34928": {
- "domain": "API_FULFILLMENT",
- "category": "BUSINESS",
- "description": "Your refund did not go through because we could not verify your payment option. Please change your payment option and try again."
- },
- "34929": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "You cannot refund this order yet since the buyer payment has not been processed. Please try again later."
- },
- "34930": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Default payment method limit exceeded. Please use a different payment option or try again later."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "34900": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.finances"
- ]
- }
- ]
- }
- },
- "/order/{orderId}/shipping_fulfillment": {
- "get": {
- "tags": [
- "shipping_fulfillment"
- ],
- "description": "Use this call to retrieve the contents of all fulfillments currently defined for a specified order based on the order's unique identifier, orderId. This value is returned in the getOrders call's members.orderId field when you search for orders by creation date or shipment status.",
- "operationId": "getShippingFulfillments",
- "parameters": [
- {
- "name": "orderId",
- "in": "path",
- "description": "This path parameter is used to specify the unique identifier of the order associated with the shipping fulfillments being retrieved.
Use the getOrders method to retrieve order IDs. Order ID values are also shown in My eBay/Seller Hub.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ShippingFulfillmentPagedCollection"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "32100": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid order ID: {orderId}"
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "30500": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "System error"
+ "/payment_dispute/{payment_dispute_id}/fetch_evidence_content": {
+ "get": {
+ "tags": [
+ "payment_dispute"
+ ],
+ "summary": "Get Payment Dispute Evidence File",
+ "description": "This call retrieves a specific evidence file for a payment dispute. The following three identifying parameters are needed in the call URI:- payment_dispute_id: the identifier of the payment dispute. The identifier of each payment dispute is returned in the getPaymentDisputeSummaries response.
- evidence_id: the identifier of the evidential file set. The identifier of an evidential file set for a payment dispute is returned under the evidence array in the getPaymentDispute response.
- file_id: the identifier of an evidential file. This file must belong to the evidential file set identified through the evidence_id query parameter. The identifier of each evidential file is returned under the evidence.files array in the getPaymentDispute response.
An actual binary file is returned if the call is successful. An error will occur if any of three identifiers are invalid.
",
+ "operationId": "fetchEvidenceContent",
+ "parameters": [
+ {
+ "name": "payment_dispute_id",
+ "in": "path",
+ "description": "This path parameter is used to specify the unique identifier of the payment dispute associated with the evidence file being retrieved.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "evidence_id",
+ "in": "query",
+ "description": "This query parameter is used to specify the unique identifier of the evidential file set.
The identifier of an evidential file set for a payment dispute is returned under the evidence array in the getPaymentDispute response.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "file_id",
+ "in": "query",
+ "description": "This query parameter is used to specify the unique identifier of an evidential file. This file must belong to the evidential file set identified through the evidence_id query parameter.
The identifier of each evidential file is returned under the evidence.files array in the getPaymentDispute response.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/octet-stream": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "33002": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid Evidence Id"
+ },
+ "33003": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid Evidence File Id"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Invalid Payment Dispute Id",
+ "x-response-codes": {
+ "errors": {
+ "33001": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid Payment Dispute Id"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "33000": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
+ ]
+ }
+ ]
+ },
+ "servers": [
+ {
+ "url": "https://apiz.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/fulfillment/v1"
+ }
+ }
}
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment",
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly"
]
- }
- ]
- },
- "post": {
- "tags": [
- "shipping_fulfillment"
- ],
- "description": "When you group an order's line items into one or more packages, each package requires a corresponding plan for handling, addressing, and shipping; this is a shipping fulfillment. For each package, execute this call once to generate a shipping fulfillment associated with that package.
Note: A single line item in an order can consist of multiple units of a purchased item, and one unit can consist of multiple parts or components. Although these components might be provided by the manufacturer in separate packaging, the seller must include all components of a given line item in the same package.
Before using this call for a given package, you must determine which line items are in the package. If the package has been shipped, you should provide the date of shipment in the request. If not provided, it will default to the current date and time.",
- "operationId": "createShippingFulfillment",
- "parameters": [
- {
- "name": "orderId",
- "in": "path",
- "description": "This path parameter is used to specify the unique identifier of the order associated with the shipping fulfillment being created.
Use the getOrders method to retrieve order IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "fulfillment payload",
- "content": {
- "application/json": {
- "schema": {
- "description": "fulfillment payload",
- "$ref": "#/components/schemas/ShippingFulfillmentDetails"
- }
- }
- },
- "required": true
},
- "responses": {
- "201": {
- "description": "Created. The call also returns the following location response header:
{ENV}/sell/fulfillment/v1/order/{ORDERID}/shipping_fulfillment/{FULFILLMENTID}
The ENV string is the HTTPS path to the same eBay supported environment in which this call was issued. The ORDERID parameter is the unique identifier of the order addressed by this call; for example, 01-03955-36441. The FULFILLMENTID parameter identifies the newly created fulfillment; for example, 9405509699937003457459. Use this Get Fulfillment URI to retrieve the contents of the new fulfillment.",
- "headers": {
- "Location": {
- "schema": {
- "type": "string",
- "description": "The location response header contains the getShippingFulfillment URI to retrieve the contents of the newly created shipping fulfillment. The URL includes the eBay-assigned fulfillmentId, which you can use to reference the shipping fulfillment."
- }
- }
+ "/payment_dispute/{payment_dispute_id}/activity": {
+ "get": {
+ "tags": [
+ "payment_dispute"
+ ],
+ "summary": "Get Payment Dispute Activity",
+ "description": "This method retrieve a log of activity for a payment dispute. The identifier of the payment dispute is passed in as a path parameter. The output includes a timestamp for each action of the payment dispute, from creation to resolution, and all steps in between.",
+ "operationId": "getActivities",
+ "parameters": [
+ {
+ "name": "payment_dispute_id",
+ "in": "path",
+ "description": "This parameter is used to specify the unique identifier of the payment dispute associated with the activity log being retrieved.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PaymentDisputeActivityHistory"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request"
+ },
+ "404": {
+ "description": "Invalid Payment Dispute Id",
+ "x-response-codes": {
+ "errors": {
+ "33001": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid Payment Dispute Id"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "33000": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
+ ]
+ }
+ ]
},
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "32100": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid Order Id: {orderId}"
- },
- "32200": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid line item id: {lineItemId}"
- },
- "32210": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Duplicate line item in the request"
- },
- "32300": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid shipment tracking number or carrier"
- },
- "32400": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Requested user is suspended"
- },
- "32500": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid shipped date"
- },
- "32600": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid input data"
- },
- "34100": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Maximum tracking number for order is exceeded"
- },
- "34200": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Line Items contain Global Shipping Program and non-Global Shipping Program orders"
- },
- "34300": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Mark As Shipped for multiple Global Shipping Program line items is not supported"
- },
- "34500": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Please use PUT operation for updating shipping fulfillment"
+ "servers": [
+ {
+ "url": "https://apiz.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/fulfillment/v1"
+ }
+ }
}
- }
- }
- },
- "409": {
- "description": "Conflict"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "30500": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "System error"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment"
]
- }
- ]
- }
- },
- "/order/{orderId}/shipping_fulfillment/{fulfillmentId}": {
- "get": {
- "tags": [
- "shipping_fulfillment"
- ],
- "description": "Use this call to retrieve the contents of a fulfillment based on its unique identifier, fulfillmentId (combined with the associated order's orderId). The fulfillmentId value was originally generated by the createShippingFulfillment call, and is returned by the getShippingFulfillments call in the members.fulfillmentId field.",
- "operationId": "getShippingFulfillment",
- "parameters": [
- {
- "name": "fulfillmentId",
- "in": "path",
- "description": "This path parameter is used to specify the unique identifier of the shipping fulfillment being retrieved.
Use the getShippingFulfillments method to retrieved fulfillment IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "orderId",
- "in": "path",
- "description": "This path parameter is used to specify the unique identifier of the order associated with the shipping fulfillment being retrieved.
Use the getOrders method to retrieve order IDs. Order ID values are also shown in My eBay/Seller Hub.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ShippingFulfillment"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "32100": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid order ID: {orderId}"
- },
- "32110": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid shipping fulfillment ID: {fulfillmentId}"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "30500": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "System error"
- }
- }
- }
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment",
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly"
- ]
- }
- ]
- }
- },
- "/payment_dispute/{payment_dispute_id}": {
- "get": {
- "tags": [
- "payment_dispute"
- ],
- "summary": "Get Payment Dispute Details",
- "description": "This method retrieves detailed information on a specific payment dispute. The payment dispute identifier is passed in as path parameter at the end of the call URI.
Below is a summary of the information that is retrieved:- Current status of payment dispute
- Amount of the payment dispute
- Reason the payment dispute was opened
- Order and line items associated with the payment dispute
- Seller response options if an action is currently required on the payment dispute
- Details on the results of the payment dispute if it has been closed
- Details on any evidence that was provided by the seller to fight the payment dispute
",
- "operationId": "getPaymentDispute",
- "parameters": [
- {
- "name": "payment_dispute_id",
- "in": "path",
- "description": "This parameter is used to specify the unique identifier of the payment dispute being retrieved.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/PaymentDispute"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request"
- },
- "404": {
- "description": "Invalid Payment Dispute Id",
- "x-response-codes": {
- "errors": {
- "33001": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid Payment Dispute Id"
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "33000": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ "/payment_dispute_summary": {
+ "get": {
+ "tags": [
+ "payment_dispute"
+ ],
+ "summary": "Search Payment Dispute by Filters",
+ "description": "This method is used retrieve one or more payment disputes filed against the seller. These payment disputes can be open or recently closed. The following filter types are available in the request payload to control the payment disputes that are returned:- Dispute filed against a specific order (order_id parameter is used)
- Dispute(s) filed by a specific buyer (buyer_username parameter is used)
- Dispute(s) filed within a specific date range (open_date_from and/or open_date_to parameters are used)
- Disputes in a specific state (payment_dispute_status parameter is used)
More than one of these filter types can be used together. See the request payload request fields for more information about how each filter is used.
If none of the filters are used, all open and recently closed payment disputes are returned.
Pagination is also available. See the limit and offset fields for more information on how pagination is used for this method.",
+ "operationId": "getPaymentDisputeSummaries",
+ "parameters": [
+ {
+ "name": "order_id",
+ "in": "query",
+ "description": "This filter is used if the seller wishes to retrieve one or more payment disputes filed against a specific order. It is possible that there can be more than one dispute filed against an order if the order has multiple line items. If this filter is used, any other filters are ignored.
Use the getOrders method to retrieve order IDs. Order ID values are also shown in My eBay/Seller Hub.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "buyer_username",
+ "in": "query",
+ "description": "This filter is used if the seller wishes to retrieve one or more payment disputes opened by a specific buyer. The string that is passed in to this query parameter is the eBay user ID of the buyer.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "open_date_from",
+ "in": "query",
+ "description": "The open_date_from and/or open_date_to date filters are used if the seller wishes to retrieve payment disputes opened within a specific date range. A maximum date range that may be set with the open_date_from and/or open_date_to filters is 90 days. These date filters use the ISO-8601 24-hour date and time format, and time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu.
The open_date_from field sets the beginning date of the date range, and can be set as far back as 18 months from the present time. If a open_date_from field is used, but a open_date_to field is not used, the open_date_to value will default to 90 days after the date specified in the open_date_from field, or to the present time if less than 90 days in the past.
The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "open_date_to",
+ "in": "query",
+ "description": "The open_date_from and/or open_date_to date filters are used if the seller wishes to retrieve payment disputes opened within a specific date range. A maximum date range that may be set with the open_date_from and/or open_date_to filters is 90 days. These date filters use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu.
The open_date_to field sets the ending date of the date range, and can be set up to 90 days from the date set in the open_date_from field.
The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "payment_dispute_status",
+ "in": "query",
+ "description": "This filter is used if the seller wishes to only retrieve payment disputes in one or more specific states. To filter by more than one status value, a separate payment_dispute_status filter must be used for each value, as shown below:
https://apiz.ebay.com/sell/fulfillment/v1/payment_dispute_summary?payment_dispute_status=OPEN&payment_dispute_status=ACTION_NEEDED
If no payment_dispute_status filter is used, payment disputes in all states are returned in the response.
See DisputeStatusEnum type for supported values.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The value passed in this query parameter sets the maximum number of payment disputes to return per page of data. The value passed in this field should be an integer from 1 to 200. If this query parameter is not set, up to 200 records will be returned on each page of results.
Min: 1
Max: 200
Default: 200",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "This field is used to specify the number of records to skip in the result set before returning the first payment dispute in the paginated response. A zero-based index is used, so if you set the offset value to 0 (default value), the first payment dispute in the result set appears at the top of the response.
Combine offset with the limit parameter to control the payment disputes returned in the response. For example, if you supply an offset value of 0 and a limit value of 10, the response will contain the first 10 payment disputes from the result set that matches the input criteria. If you supply an offset value of 10 and a limit value of 20, the response will contain payment disputes 11-30 from the result set that matches the input criteria.
Min: 0
Default: 0",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DisputeSummaryResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "33001": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid input request"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "33000": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
+ ]
+ }
+ ]
+ },
+ "servers": [
+ {
+ "url": "https://apiz.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/fulfillment/v1"
+ }
+ }
}
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
]
- }
- ]
- },
- "servers": [
- {
- "url": "https://apiz.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/fulfillment/v1"
- }
- }
- }
- ]
- },
- "/payment_dispute/{payment_dispute_id}/fetch_evidence_content": {
- "get": {
- "tags": [
- "payment_dispute"
- ],
- "summary": "Get Payment Dispute Evidence File",
- "description": "This call retrieves a specific evidence file for a payment dispute. The following three identifying parameters are needed in the call URI:- payment_dispute_id: the identifier of the payment dispute. The identifier of each payment dispute is returned in the getPaymentDisputeSummaries response.
- evidence_id: the identifier of the evidential file set. The identifier of an evidential file set for a payment dispute is returned under the evidence array in the getPaymentDispute response.
- file_id: the identifier of an evidential file. This file must belong to the evidential file set identified through the evidence_id query parameter. The identifier of each evidential file is returned under the evidence.files array in the getPaymentDispute response.
An actual binary file is returned if the call is successful. An error will occur if any of three identifiers are invalid.
",
- "operationId": "fetchEvidenceContent",
- "parameters": [
- {
- "name": "payment_dispute_id",
- "in": "path",
- "description": "This path parameter is used to specify the unique identifier of the payment dispute associated with the evidence file being retrieved.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "evidence_id",
- "in": "query",
- "description": "This query parameter is used to specify the unique identifier of the evidential file set.
The identifier of an evidential file set for a payment dispute is returned under the evidence array in the getPaymentDispute response.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "file_id",
- "in": "query",
- "description": "This query parameter is used to specify the unique identifier of an evidential file. This file must belong to the evidential file set identified through the evidence_id query parameter.
The identifier of each evidential file is returned under the evidence.files array in the getPaymentDispute response.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/octet-stream": {
- "schema": {
- "type": "array",
- "items": {
- "type": "string"
- }
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "33002": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid Evidence Id"
- },
- "33003": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid Evidence File Id"
- }
- }
- }
- },
- "404": {
- "description": "Invalid Payment Dispute Id",
- "x-response-codes": {
- "errors": {
- "33001": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid Payment Dispute Id"
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "33000": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
- }
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
- ]
- }
- ]
- },
- "servers": [
- {
- "url": "https://apiz.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/fulfillment/v1"
- }
- }
- }
- ]
- },
- "/payment_dispute/{payment_dispute_id}/activity": {
- "get": {
- "tags": [
- "payment_dispute"
- ],
- "summary": "Get Payment Dispute Activity",
- "description": "This method retrieve a log of activity for a payment dispute. The identifier of the payment dispute is passed in as a path parameter. The output includes a timestamp for each action of the payment dispute, from creation to resolution, and all steps in between.",
- "operationId": "getActivities",
- "parameters": [
- {
- "name": "payment_dispute_id",
- "in": "path",
- "description": "This parameter is used to specify the unique identifier of the payment dispute associated with the activity log being retrieved.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/PaymentDisputeActivityHistory"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request"
- },
- "404": {
- "description": "Invalid Payment Dispute Id",
- "x-response-codes": {
- "errors": {
- "33001": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid Payment Dispute Id"
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "33000": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ "/payment_dispute/{payment_dispute_id}/contest": {
+ "post": {
+ "tags": [
+ "payment_dispute"
+ ],
+ "summary": "Contest Payment Dispute",
+ "description": "This method is used if the seller wishes to contest a payment dispute initiated by the buyer. The unique identifier of the payment dispute is passed in as a path parameter, and unique identifiers for payment disputes can be retrieved with the getPaymentDisputeSummaries method.
Note: Before contesting a payment dispute, the seller must upload all supporting files using the addEvidence and updateEvidence methods. Once the seller has officially contested the dispute (using contestPaymentDispute), the addEvidence and updateEvidence methods can no longer be used. In the evidenceRequests array of the getPaymentDispute response, eBay prompts the seller with the type of supporting file(s) that will be needed to contest the payment dispute.
If a seller decides to contest a payment dispute, that seller should be prepared to provide supporting documents such as proof of delivery, proof of authentication, or other documents. The type of supporting documents that the seller will provide will depend on why the buyer filed the payment dispute.
The revision field in the request payload is required, and the returnAddress field should be supplied if the seller is expecting the buyer to return the item. See the Request Payload section for more information on these fields.",
+ "operationId": "contestPaymentDispute",
+ "parameters": [
+ {
+ "name": "payment_dispute_id",
+ "in": "path",
+ "description": "This parameter is used to specify the unique identifier of the payment dispute being contested.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ContestPaymentDisputeRequest"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "204": {
+ "description": "Success"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "33100": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid input request"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found"
+ },
+ "409": {
+ "description": "Conflict",
+ "x-response-codes": {
+ "errors": {
+ "33011": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "There was a change in payment dispute attributes. Please use get payment dispute api to get latest details."
+ },
+ "33101": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid payment dispute state"
+ },
+ "33102": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "No evidence available for contest"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "33000": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
+ ]
+ }
+ ]
+ },
+ "servers": [
+ {
+ "url": "https://apiz.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/fulfillment/v1"
+ }
+ }
}
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
]
- }
- ]
- },
- "servers": [
- {
- "url": "https://apiz.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/fulfillment/v1"
- }
- }
- }
- ]
- },
- "/payment_dispute_summary": {
- "get": {
- "tags": [
- "payment_dispute"
- ],
- "summary": "Search Payment Dispute by Filters",
- "description": "This method is used retrieve one or more payment disputes filed against the seller. These payment disputes can be open or recently closed. The following filter types are available in the request payload to control the payment disputes that are returned:- Dispute filed against a specific order (order_id parameter is used)
- Dispute(s) filed by a specific buyer (buyer_username parameter is used)
- Dispute(s) filed within a specific date range (open_date_from and/or open_date_to parameters are used)
- Disputes in a specific state (payment_dispute_status parameter is used)
More than one of these filter types can be used together. See the request payload request fields for more information about how each filter is used.
If none of the filters are used, all open and recently closed payment disputes are returned.
Pagination is also available. See the limit and offset fields for more information on how pagination is used for this method.",
- "operationId": "getPaymentDisputeSummaries",
- "parameters": [
- {
- "name": "order_id",
- "in": "query",
- "description": "This filter is used if the seller wishes to retrieve one or more payment disputes filed against a specific order. It is possible that there can be more than one dispute filed against an order if the order has multiple line items. If this filter is used, any other filters are ignored.
Use the getOrders method to retrieve order IDs. Order ID values are also shown in My eBay/Seller Hub.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "buyer_username",
- "in": "query",
- "description": "This filter is used if the seller wishes to retrieve one or more payment disputes opened by a specific buyer. The string that is passed in to this query parameter is the eBay user ID of the buyer.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "open_date_from",
- "in": "query",
- "description": "The open_date_from and/or open_date_to date filters are used if the seller wishes to retrieve payment disputes opened within a specific date range. A maximum date range that may be set with the open_date_from and/or open_date_to filters is 90 days. These date filters use the ISO-8601 24-hour date and time format, and time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu.
The open_date_from field sets the beginning date of the date range, and can be set as far back as 18 months from the present time. If a open_date_from field is used, but a open_date_to field is not used, the open_date_to value will default to 90 days after the date specified in the open_date_from field, or to the present time if less than 90 days in the past.
The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "open_date_to",
- "in": "query",
- "description": "The open_date_from and/or open_date_to date filters are used if the seller wishes to retrieve payment disputes opened within a specific date range. A maximum date range that may be set with the open_date_from and/or open_date_to filters is 90 days. These date filters use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu.
The open_date_to field sets the ending date of the date range, and can be set up to 90 days from the date set in the open_date_from field.
The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "payment_dispute_status",
- "in": "query",
- "description": "This filter is used if the seller wishes to only retrieve payment disputes in one or more specific states. To filter by more than one status value, a separate payment_dispute_status filter must be used for each value, as shown below:
https://apiz.ebay.com/sell/fulfillment/v1/payment_dispute_summary?payment_dispute_status=OPEN&payment_dispute_status=ACTION_NEEDED
If no payment_dispute_status filter is used, payment disputes in all states are returned in the response.
See DisputeStatusEnum type for supported values.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "limit",
- "in": "query",
- "description": "The value passed in this query parameter sets the maximum number of payment disputes to return per page of data. The value passed in this field should be an integer from 1 to 200. If this query parameter is not set, up to 200 records will be returned on each page of results.
Min: 1
Max: 200
Default: 200",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "This field is used to specify the number of records to skip in the result set before returning the first payment dispute in the paginated response. A zero-based index is used, so if you set the offset value to 0 (default value), the first payment dispute in the result set appears at the top of the response.
Combine offset with the limit parameter to control the payment disputes returned in the response. For example, if you supply an offset value of 0 and a limit value of 10, the response will contain the first 10 payment disputes from the result set that matches the input criteria. If you supply an offset value of 10 and a limit value of 20, the response will contain payment disputes 11-30 from the result set that matches the input criteria.
Min: 0
Default: 0",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/DisputeSummaryResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "33001": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid input request"
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "33000": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
- }
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
- ]
- }
- ]
- },
- "servers": [
- {
- "url": "https://apiz.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/fulfillment/v1"
- }
- }
- }
- ]
- },
- "/payment_dispute/{payment_dispute_id}/contest": {
- "post": {
- "tags": [
- "payment_dispute"
- ],
- "summary": "Contest Payment Dispute",
- "description": "This method is used if the seller wishes to contest a payment dispute initiated by the buyer. The unique identifier of the payment dispute is passed in as a path parameter, and unique identifiers for payment disputes can be retrieved with the getPaymentDisputeSummaries method.
Note: Before contesting a payment dispute, the seller must upload all supporting files using the addEvidence and updateEvidence methods. Once the seller has officially contested the dispute (using contestPaymentDispute), the addEvidence and updateEvidence methods can no longer be used. In the evidenceRequests array of the getPaymentDispute response, eBay prompts the seller with the type of supporting file(s) that will be needed to contest the payment dispute.
If a seller decides to contest a payment dispute, that seller should be prepared to provide supporting documents such as proof of delivery, proof of authentication, or other documents. The type of supporting documents that the seller will provide will depend on why the buyer filed the payment dispute.
The revision field in the request payload is required, and the returnAddress field should be supplied if the seller is expecting the buyer to return the item. See the Request Payload section for more information on these fields.",
- "operationId": "contestPaymentDispute",
- "parameters": [
- {
- "name": "payment_dispute_id",
- "in": "path",
- "description": "This parameter is used to specify the unique identifier of the payment dispute being contested.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ContestPaymentDisputeRequest"
- }
- }
- },
- "required": false
- },
- "responses": {
- "204": {
- "description": "Success"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "33100": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid input request"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "33011": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "There was a change in payment dispute attributes. Please use get payment dispute api to get latest details."
- },
- "33101": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid payment dispute state"
- },
- "33102": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "No evidence available for contest"
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "33000": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ "/payment_dispute/{payment_dispute_id}/accept": {
+ "post": {
+ "tags": [
+ "payment_dispute"
+ ],
+ "summary": "Accept Payment Dispute",
+ "description": "This method is used if the seller wishes to accept a payment dispute. The unique identifier of the payment dispute is passed in as a path parameter, and unique identifiers for payment disputes can be retrieved with the getPaymentDisputeSummaries method.
The revision field in the request payload is required, and the returnAddress field should be supplied if the seller is expecting the buyer to return the item. See the Request Payload section for more information on theste fields.",
+ "operationId": "acceptPaymentDispute",
+ "parameters": [
+ {
+ "name": "payment_dispute_id",
+ "in": "path",
+ "description": "This parameter is used to specify the unique identifier of the payment dispute being accepted.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AcceptPaymentDisputeRequest"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "204": {
+ "description": "Success"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "33100": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid input request"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found"
+ },
+ "409": {
+ "description": "Conflict",
+ "x-response-codes": {
+ "errors": {
+ "33011": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "There was a change in payment dispute attributes. Please use get payment dispute api to get latest details."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "33000": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
+ ]
+ }
+ ]
+ },
+ "servers": [
+ {
+ "url": "https://apiz.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/fulfillment/v1"
+ }
+ }
}
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
]
- }
- ]
- },
- "servers": [
- {
- "url": "https://apiz.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/fulfillment/v1"
- }
- }
- }
- ]
- },
- "/payment_dispute/{payment_dispute_id}/accept": {
- "post": {
- "tags": [
- "payment_dispute"
- ],
- "summary": "Accept Payment Dispute",
- "description": "This method is used if the seller wishes to accept a payment dispute. The unique identifier of the payment dispute is passed in as a path parameter, and unique identifiers for payment disputes can be retrieved with the getPaymentDisputeSummaries method.
The revision field in the request payload is required, and the returnAddress field should be supplied if the seller is expecting the buyer to return the item. See the Request Payload section for more information on theste fields.",
- "operationId": "acceptPaymentDispute",
- "parameters": [
- {
- "name": "payment_dispute_id",
- "in": "path",
- "description": "This parameter is used to specify the unique identifier of the payment dispute being accepted.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/AcceptPaymentDisputeRequest"
- }
- }
- },
- "required": false
},
- "responses": {
- "204": {
- "description": "Success"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "33100": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid input request"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "33011": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "There was a change in payment dispute attributes. Please use get payment dispute api to get latest details."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "33000": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ "/payment_dispute/{payment_dispute_id}/upload_evidence_file": {
+ "post": {
+ "tags": [
+ "payment_dispute"
+ ],
+ "summary": "Upload an Evidence File",
+ "description": "This method is used to upload an evidence file for a contested payment dispute. The unique identifier of the payment dispute is passed in as a path parameter, and unique identifiers for payment disputes can be retrieved with the getPaymentDisputeSummaries method.
Note: The uploadEvidenceFile only uploads an encrypted, binary image file (using multipart/form-data HTTP request header), and does not have a JSON-based request payload.
Use 'file' as the name of the key that you use to upload the image file. The upload will not be successful if a different key name is used.
The three image formats supported at this time are .JPEG, .JPG, and .PNG.
After the file is successfully uploaded, the seller will need to grab the fileId value in the response payload to add this file to a new evidence set using the addEvidence method, or to add this file to an existing evidence set using the updateEvidence method.",
+ "operationId": "uploadEvidenceFile",
+ "parameters": [
+ {
+ "name": "payment_dispute_id",
+ "in": "path",
+ "description": "This parameter is used to specify the unique identifier of the contested payment dispute for which the user intends to upload an evidence file.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to multipart/form-data.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/FileEvidence"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "33005": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "File type is invalid."
+ },
+ "33006": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "File size should be 1.5 MB or less."
+ },
+ "33106": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "The file name should not be empty and should not exceed 255 characters."
+ },
+ "33107": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Only one file can be uploaded per request."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "x-response-codes": {
+ "errors": {
+ "33001": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid Payment Dispute Id"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "x-response-codes": {
+ "errors": {
+ "33004": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Upload file for evidence is not permitted for given payment dispute state."
+ },
+ "33105": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "You reached the maximum number of files you can upload."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "33000": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
+ ]
+ }
+ ]
+ },
+ "servers": [
+ {
+ "url": "https://apiz.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/fulfillment/v1"
+ }
+ }
}
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
]
- }
- ]
- },
- "servers": [
- {
- "url": "https://apiz.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/fulfillment/v1"
- }
- }
- }
- ]
- },
- "/payment_dispute/{payment_dispute_id}/upload_evidence_file": {
- "post": {
- "tags": [
- "payment_dispute"
- ],
- "summary": "Upload an Evidence File",
- "description": "This method is used to upload an evidence file for a contested payment dispute. The unique identifier of the payment dispute is passed in as a path parameter, and unique identifiers for payment disputes can be retrieved with the getPaymentDisputeSummaries method.
Note: The uploadEvidenceFile only uploads an encrypted, binary image file (using multipart/form-data HTTP request header), and does not have a JSON-based request payload.
Use 'file' as the name of the key that you use to upload the image file. The upload will not be successful if a different key name is used.
The three image formats supported at this time are .JPEG, .JPG, and .PNG.
After the file is successfully uploaded, the seller will need to grab the fileId value in the response payload to add this file to a new evidence set using the addEvidence method, or to add this file to an existing evidence set using the updateEvidence method.",
- "operationId": "uploadEvidenceFile",
- "parameters": [
- {
- "name": "payment_dispute_id",
- "in": "path",
- "description": "This parameter is used to specify the unique identifier of the contested payment dispute for which the user intends to upload an evidence file.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to multipart/form-data.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/FileEvidence"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "33005": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "File type is invalid."
- },
- "33006": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "File size should be 1.5 MB or less."
- },
- "33106": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "The file name should not be empty and should not exceed 255 characters."
- },
- "33107": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Only one file can be uploaded per request."
- }
- }
- }
- },
- "404": {
- "description": "Not Found",
- "x-response-codes": {
- "errors": {
- "33001": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid Payment Dispute Id"
- }
- }
- }
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "33004": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Upload file for evidence is not permitted for given payment dispute state."
- },
- "33105": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "You reached the maximum number of files you can upload."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "33000": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
- }
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
+ "/payment_dispute/{payment_dispute_id}/add_evidence": {
+ "post": {
+ "tags": [
+ "payment_dispute"
+ ],
+ "summary": "Add an Evidence File",
+ "description": "This method is used by the seller to add one or more evidence files to address a payment dispute initiated by the buyer. The unique identifier of the payment dispute is passed in as a path parameter, and unique identifiers for payment disputes can be retrieved with the getPaymentDisputeSummaries method.
Note: All evidence files should be uploaded using addEvidence and updateEvidence before the seller decides to contest the payment dispute. Once the seller has officially contested the dispute (using contestPaymentDispute or through My eBay), the addEvidence and updateEvidence methods can no longer be used. In the evidenceRequests array of the getPaymentDispute response, eBay prompts the seller with the type of evidence file(s) that will be needed to contest the payment dispute.
The file(s) to add are identified through the files array in the request payload. Adding one or more new evidence files for a payment dispute triggers the creation of an evidence file, and the unique identifier for the new evidence file is automatically generated and returned in the evidenceId field of the addEvidence response payload upon a successful call.
The type of evidence being added should be specified in the evidenceType field. All files being added (if more than one) should correspond to this evidence type.
Upon a successful call, an evidenceId value is returned in the response. This indicates that a new evidence set has been created for the payment dispute, and this evidence set includes the evidence file(s) that were passed in to the fileId array. The evidenceId value will be needed if the seller wishes to add to the evidence set by using the updateEvidence method, or if they want to retrieve a specific evidence file within the evidence set by using the fetchEvidenceContent method.",
+ "operationId": "addEvidence",
+ "parameters": [
+ {
+ "name": "payment_dispute_id",
+ "in": "path",
+ "description": "This parameter is used to specify the unique identifier of the contested payment dispute for which the seller wishes to add evidence files.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AddEvidencePaymentDisputeRequest"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AddEvidencePaymentDisputeResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "33003": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid Evidence File Id"
+ },
+ "33007": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid line items."
+ },
+ "33008": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid evidence type."
+ },
+ "33009": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "User did not echo back the evidence metadata correctly."
+ },
+ "33100": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid input request"
+ },
+ "33103": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Exceed allowed file count"
+ },
+ "33104": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "The combined size of attached files should be 1.5MB or less."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "x-response-codes": {
+ "errors": {
+ "33001": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid Payment Dispute Id"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "x-response-codes": {
+ "errors": {
+ "33004": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Upload file for evidence is not permitted for given payment dispute state."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "33000": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
+ ]
+ }
+ ]
+ },
+ "servers": [
+ {
+ "url": "https://apiz.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/fulfillment/v1"
+ }
+ }
+ }
]
- }
- ]
- },
- "servers": [
- {
- "url": "https://apiz.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/fulfillment/v1"
- }
- }
- }
- ]
- },
- "/payment_dispute/{payment_dispute_id}/add_evidence": {
- "post": {
- "tags": [
- "payment_dispute"
- ],
- "summary": "Add an Evidence File",
- "description": "This method is used by the seller to add one or more evidence files to address a payment dispute initiated by the buyer. The unique identifier of the payment dispute is passed in as a path parameter, and unique identifiers for payment disputes can be retrieved with the getPaymentDisputeSummaries method.
Note: All evidence files should be uploaded using addEvidence and updateEvidence before the seller decides to contest the payment dispute. Once the seller has officially contested the dispute (using contestPaymentDispute or through My eBay), the addEvidence and updateEvidence methods can no longer be used. In the evidenceRequests array of the getPaymentDispute response, eBay prompts the seller with the type of evidence file(s) that will be needed to contest the payment dispute.
The file(s) to add are identified through the files array in the request payload. Adding one or more new evidence files for a payment dispute triggers the creation of an evidence file, and the unique identifier for the new evidence file is automatically generated and returned in the evidenceId field of the addEvidence response payload upon a successful call.
The type of evidence being added should be specified in the evidenceType field. All files being added (if more than one) should correspond to this evidence type.
Upon a successful call, an evidenceId value is returned in the response. This indicates that a new evidence set has been created for the payment dispute, and this evidence set includes the evidence file(s) that were passed in to the fileId array. The evidenceId value will be needed if the seller wishes to add to the evidence set by using the updateEvidence method, or if they want to retrieve a specific evidence file within the evidence set by using the fetchEvidenceContent method.",
- "operationId": "addEvidence",
- "parameters": [
- {
- "name": "payment_dispute_id",
- "in": "path",
- "description": "This parameter is used to specify the unique identifier of the contested payment dispute for which the seller wishes to add evidence files.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/AddEvidencePaymentDisputeRequest"
- }
- }
- },
- "required": false
},
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/AddEvidencePaymentDisputeResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "33003": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid Evidence File Id"
- },
- "33007": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid line items."
- },
- "33008": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid evidence type."
- },
- "33009": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "User did not echo back the evidence metadata correctly."
- },
- "33100": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid input request"
- },
- "33103": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Exceed allowed file count"
- },
- "33104": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "The combined size of attached files should be 1.5MB or less."
- }
- }
- }
- },
- "404": {
- "description": "Not Found",
- "x-response-codes": {
- "errors": {
- "33001": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid Payment Dispute Id"
- }
- }
- }
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "33004": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Upload file for evidence is not permitted for given payment dispute state."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "33000": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ "/payment_dispute/{payment_dispute_id}/update_evidence": {
+ "post": {
+ "tags": [
+ "payment_dispute"
+ ],
+ "summary": "Update evidence",
+ "description": "This method is used by the seller to update an existing evidence set for a payment dispute with one or more evidence files. The unique identifier of the payment dispute is passed in as a path parameter, and unique identifiers for payment disputes can be retrieved with the getPaymentDisputeSummaries method.
Note: All evidence files should be uploaded using addEvidence and updateEvidence before the seller decides to contest the payment dispute. Once the seller has officially contested the dispute (using contestPaymentDispute or through My eBay), the addEvidence and updateEvidence methods can no longer be used. In the evidenceRequests array of the getPaymentDispute response, eBay prompts the seller with the type of evidence file(s) that will be needed to contest the payment dispute.
The unique identifier of the evidence set to update is specified through the evidenceId field, and the file(s) to add are identified through the files array in the request payload. The unique identifier for an evidence file is automatically generated and returned in the fileId field of the uploadEvidence response payload upon a successful call. Sellers must make sure to capture the fileId value for each evidence file that is uploaded with the uploadEvidence method.
The type of evidence being added should be specified in the evidenceType field. All files being added (if more than one) should correspond to this evidence type.
Upon a successful call, an http status code of 204 Success is returned. There is no response payload unless an error occurs. To verify that a new file is a part of the evidence set, the seller can use the fetchEvidenceContent method, passing in the proper evidenceId and fileId values.",
+ "operationId": "updateEvidence",
+ "parameters": [
+ {
+ "name": "payment_dispute_id",
+ "in": "path",
+ "description": "This parameter is used to specify the unique identifier of the contested payment dispute for which the user plans to update the evidence set.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UpdateEvidencePaymentDisputeRequest"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "204": {
+ "description": "Success"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "33003": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid Evidence File Id"
+ },
+ "33007": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid line items."
+ },
+ "33008": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid evidence type."
+ },
+ "33009": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "User did not echo back the evidence metadata correctly."
+ },
+ "33010": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Evidence Id is invalid"
+ },
+ "33100": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid input request"
+ },
+ "33103": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Exceed allowed file count"
+ },
+ "33104": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "The combined size of attached files should be 1.5MB or less."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "x-response-codes": {
+ "errors": {
+ "33001": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Invalid Payment Dispute Id"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "x-response-codes": {
+ "errors": {
+ "33004": {
+ "domain": "API_FULFILLMENT",
+ "category": "REQUEST",
+ "description": "Upload file for evidence is not permitted for given payment dispute state."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "33000": {
+ "domain": "API_FULFILLMENT",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
+ ]
+ }
+ ]
+ },
+ "servers": [
+ {
+ "url": "https://apiz.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/fulfillment/v1"
+ }
+ }
}
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
]
- }
- ]
- },
- "servers": [
- {
- "url": "https://apiz.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/fulfillment/v1"
- }
- }
}
- ]
},
- "/payment_dispute/{payment_dispute_id}/update_evidence": {
- "post": {
- "tags": [
- "payment_dispute"
- ],
- "summary": "Update evidence",
- "description": "This method is used by the seller to update an existing evidence set for a payment dispute with one or more evidence files. The unique identifier of the payment dispute is passed in as a path parameter, and unique identifiers for payment disputes can be retrieved with the getPaymentDisputeSummaries method.
Note: All evidence files should be uploaded using addEvidence and updateEvidence before the seller decides to contest the payment dispute. Once the seller has officially contested the dispute (using contestPaymentDispute or through My eBay), the addEvidence and updateEvidence methods can no longer be used. In the evidenceRequests array of the getPaymentDispute response, eBay prompts the seller with the type of evidence file(s) that will be needed to contest the payment dispute.
The unique identifier of the evidence set to update is specified through the evidenceId field, and the file(s) to add are identified through the files array in the request payload. The unique identifier for an evidence file is automatically generated and returned in the fileId field of the uploadEvidence response payload upon a successful call. Sellers must make sure to capture the fileId value for each evidence file that is uploaded with the uploadEvidence method.
The type of evidence being added should be specified in the evidenceType field. All files being added (if more than one) should correspond to this evidence type.
Upon a successful call, an http status code of 204 Success is returned. There is no response payload unless an error occurs. To verify that a new file is a part of the evidence set, the seller can use the fetchEvidenceContent method, passing in the proper evidenceId and fileId values.",
- "operationId": "updateEvidence",
- "parameters": [
- {
- "name": "payment_dispute_id",
- "in": "path",
- "description": "This parameter is used to specify the unique identifier of the contested payment dispute for which the user plans to update the evidence set.
Use the getPaymentDisputeSummaries method to retrieve payment dispute IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/UpdateEvidencePaymentDisputeRequest"
- }
- }
- },
- "required": false
- },
- "responses": {
- "204": {
- "description": "Success"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "33003": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid Evidence File Id"
- },
- "33007": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid line items."
- },
- "33008": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid evidence type."
- },
- "33009": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "User did not echo back the evidence metadata correctly."
- },
- "33010": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Evidence Id is invalid"
- },
- "33100": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid input request"
- },
- "33103": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Exceed allowed file count"
- },
- "33104": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "The combined size of attached files should be 1.5MB or less."
- }
- }
- }
- },
- "404": {
- "description": "Not Found",
- "x-response-codes": {
- "errors": {
- "33001": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Invalid Payment Dispute Id"
- }
- }
- }
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "33004": {
- "domain": "API_FULFILLMENT",
- "category": "REQUEST",
- "description": "Upload file for evidence is not permitted for given payment dispute state."
+ "components": {
+ "schemas": {
+ "AcceptPaymentDisputeRequest": {
+ "type": "object",
+ "properties": {
+ "returnAddress": {
+ "description": "This container is used if the seller wishes to provide a return address to the buyer. This container should be used if the seller is requesting that the buyer return the item.",
+ "$ref": "#/components/schemas/ReturnAddress"
+ },
+ "revision": {
+ "type": "integer",
+ "description": "This integer value indicates the revision number of the payment dispute. This field is required. The current revision number for a payment dispute can be retrieved with the getPaymentDispute method. Each time an action is taken against a payment dispute, this integer value increases by 1.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used by base request of the acceptPaymentDispute method."
+ },
+ "AddEvidencePaymentDisputeRequest": {
+ "type": "object",
+ "properties": {
+ "evidenceType": {
+ "type": "string",
+ "description": "This field is used to indicate the type of evidence being provided through one or more evidence files. All evidence files (if more than one) should be associated with the evidence type passed in this field.
See the EvidenceTypeEnum type for the supported evidence types. For implementation help, refer to eBay API documentation"
+ },
+ "files": {
+ "type": "array",
+ "description": "This array is used to specify one or more evidence files that will become part of a new evidence set associated with a payment dispute. At least one evidence file must be specified in the files array.",
+ "items": {
+ "$ref": "#/components/schemas/FileEvidence"
+ }
+ },
+ "lineItems": {
+ "type": "array",
+ "description": "This array identifies the order line item(s) for which the evidence file(s) will be applicable.
These values are returned under the evidenceRequests.lineItems array in the getPaymentDispute response.",
+ "items": {
+ "$ref": "#/components/schemas/OrderLineItems"
+ }
+ }
+ },
+ "description": "This type is used by the request payload of the addEvidence method. The addEvidence method is used to create a new evidence set against a payment dispute with one or more evidence files."
+ },
+ "AddEvidencePaymentDisputeResponse": {
+ "type": "object",
+ "properties": {
+ "evidenceId": {
+ "type": "string",
+ "description": "The value returned in this field is the unique identifier of the newly-created evidence set. Upon a successful call, this value is automatically genererated. This new evidence set for the payment dispute includes the evidence file(s) that were passed in to the fileId array in the request payload. The evidenceId value will be needed if the seller wishes to add to the evidence set by using the updateEvidence method, or if they want to retrieve a specific evidence file within the evidence set by using the fetchEvidenceContent method."
+ }
+ },
+ "description": "This type is used by the response payload of the addEvidence method. Its only field is an unique identifier of an evidence set."
+ },
+ "Address": {
+ "type": "object",
+ "properties": {
+ "addressLine1": {
+ "type": "string",
+ "description": "The first line of the street address.
Note: addressLine1 will not be returned for any order that is more than 90 days old."
+ },
+ "addressLine2": {
+ "type": "string",
+ "description": "The second line of the street address. This field can be used for additional address information, such as a suite or apartment number. This field will be returned if defined for the shipping address.
Note: addressLine2 will not be returned for any order that is more than 90 days old."
+ },
+ "city": {
+ "type": "string",
+ "description": "The city of the shipping destination."
+ },
+ "countryCode": {
+ "type": "string",
+ "description": "The country of the shipping destination, represented as a two-letter ISO 3166-1 alpha-2 country code. For example, US represents the United States, and DE represents Germany. For implementation help, refer to eBay API documentation"
+ },
+ "county": {
+ "type": "string",
+ "description": "The county of the shipping destination. Counties typically, but not always, contain multiple cities or towns. This field is returned if known/available."
+ },
+ "postalCode": {
+ "type": "string",
+ "description": "The postal code of the shipping destination. Usually referred to as Zip codes in the US. Most countries have postal codes, but not all. The postal code will be returned if applicable."
+ },
+ "stateOrProvince": {
+ "type": "string",
+ "description": "The state or province of the shipping destination. Most countries have states or provinces, but not all. The state or province will be returned if applicable."
+ }
+ },
+ "description": "This type contains the details of a geographical address."
+ },
+ "Amount": {
+ "type": "object",
+ "properties": {
+ "convertedFromCurrency": {
+ "type": "string",
+ "description": "A three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency. For implementation help, refer to eBay API documentation"
+ },
+ "convertedFromValue": {
+ "type": "string",
+ "description": "The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field."
+ },
+ "currency": {
+ "type": "string",
+ "description": "A three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.
Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation"
+ },
+ "value": {
+ "type": "string",
+ "description": "The monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.
Required in the amount type."
+ }
+ },
+ "description": "This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable."
+ },
+ "AppliedPromotion": {
+ "type": "object",
+ "properties": {
+ "description": {
+ "type": "string",
+ "description": "A description of the applied sales promotion."
+ },
+ "discountAmount": {
+ "description": "The monetary amount of the sales promotion.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "promotionId": {
+ "type": "string",
+ "description": "An eBay-generated unique identifier of the sales promotion.
Multiple types of sales promotions are available to eBay Store owners, including order size/volume discounts, shipping discounts, special coupons, and price markdowns. Sales promotions can be managed through the Marketing tab of Seller Hub in My eBay, or by using the Trading API's SetPromotionalSale call or the Marketing API's createItemPromotion method."
+ }
+ },
+ "description": "This type contains information about a sales promotion that is applied to a line item."
+ },
+ "AppointmentDetails": {
+ "type": "object",
+ "properties": {
+ "appointmentEndTime": {
+ "type": "string",
+ "description": "The date and time the appointment ends, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Required for tire installation.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2022-10-28T00:00:00.000Z"
+ },
+ "appointmentStartTime": {
+ "type": "string",
+ "description": "The date and time the appointment begins, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2022-10-28T00:10:00.000Z"
+ },
+ "appointmentStatus": {
+ "type": "string",
+ "description": "The status of the appointment. For implementation help, refer to eBay API documentation"
+ },
+ "appointmentType": {
+ "type": "string",
+ "description": "The type of appointment. MACRO appointments only have a start time (not bounded with end time). TIME_SLOT appointments have a period (both start time and end time). Required for tire installation. For implementation help, refer to eBay API documentation"
+ },
+ "appointmentWindow": {
+ "type": "string",
+ "description": "Appointment window for MACRO appointments. For implementation help, refer to eBay API documentation"
+ },
+ "serviceProviderAppointmentDate": {
+ "type": "string",
+ "description": "Service provider date of the appointment (no time stamp). Returned only for MACRO appointment types."
+ }
+ },
+ "description": "This type contains information used by the installation provider concerning appointment details selected by the buyer"
+ },
+ "Buyer": {
+ "type": "object",
+ "properties": {
+ "buyerRegistrationAddress": {
+ "description": "Buyer's contact information that includes the buyer's name, email, phone number, and address.",
+ "$ref": "#/components/schemas/ExtendedContact"
+ },
+ "taxAddress": {
+ "description": "This container consists of address information that can be used by sellers for tax purpose.
Note: When using the eBay vault program, if an item is shipped to a vault, the tax address will be the vault address.",
+ "$ref": "#/components/schemas/TaxAddress"
+ },
+ "taxIdentifier": {
+ "description": "This container consists of taxpayer identification information for buyers from Italy, Spain, or Guatemala. It is currently only returned for orders occurring on the eBay Italy or eBay Spain marketplaces.
Note: Currently, the taxIdentifier container is only returned in getOrder and not in getOrders. So, if a seller wanted to view a buyer's tax information for a particular order returned in getOrders, that seller would need to use the orderId value for that particular order, and then run a getOrder call against that order ID. ",
+ "$ref": "#/components/schemas/TaxIdentifier"
+ },
+ "username": {
+ "type": "string",
+ "description": "The buyer's eBay user ID."
+ }
+ },
+ "description": "This type contains information about the order's buyer."
+ },
+ "CancelRequest": {
+ "type": "object",
+ "properties": {
+ "cancelCompletedDate": {
+ "type": "string",
+ "description": "The date and time that the order cancellation was completed, if applicable. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the cancellation request has actually been approved by the seller.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "cancelInitiator": {
+ "type": "string",
+ "description": "This string value indicates the party who made the initial cancellation request. Typically, either the 'Buyer' or 'Seller'. If a cancellation request has been made, this field should be returned."
+ },
+ "cancelReason": {
+ "type": "string",
+ "description": "The reason why the cancelInitiator initiated the cancellation request. Cancellation reasons for a buyer might include 'order placed by mistake' or 'order won't arrive in time'. For a seller, a typical cancellation reason is 'out of stock'. If a cancellation request has been made, this field should be returned."
+ },
+ "cancelRequestedDate": {
+ "type": "string",
+ "description": "The date and time that the order cancellation was requested. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is returned for each cancellation request.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "cancelRequestId": {
+ "type": "string",
+ "description": "The unique identifier of the order cancellation request. This field is returned for each cancellation request."
+ },
+ "cancelRequestState": {
+ "type": "string",
+ "description": "The current stage or condition of the cancellation request. This field is returned for each cancellation request. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type contains information about a buyer request to cancel an order."
+ },
+ "CancelStatus": {
+ "type": "object",
+ "properties": {
+ "cancelledDate": {
+ "type": "string",
+ "description": "The date and time the order was cancelled, if applicable. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "cancelRequests": {
+ "type": "array",
+ "description": "This array contains details of one or more buyer requests to cancel the order.
For the getOrders call: This array is returned but is always empty.
For the getOrder call: This array is returned fully populated with information about any cancellation requests.",
+ "items": {
+ "$ref": "#/components/schemas/CancelRequest"
+ }
+ },
+ "cancelState": {
+ "type": "string",
+ "description": "The state of the order with regard to cancellation. This field is always returned, and if there are no cancellation requests, a value of NONE_REQUESTED is returned. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type contains information about any requests that have been made to cancel an order."
+ },
+ "Charge": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "This container shows the amount and currency of the charge.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "chargeType": {
+ "type": "string",
+ "description": "This field shows the type of buyer charge
Note: Currently, the only supported charge type is BUYER_PROTECTION. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used to display the charge type and the amount of the charge against the buyer."
+ },
+ "ContestPaymentDisputeRequest": {
+ "type": "object",
+ "properties": {
+ "note": {
+ "type": "string",
+ "description": "This field shows information that the seller provides about the dispute, such as the basis for the dispute, any relevant evidence, tracking numbers, and so forth.
Max Length: 1000 characters."
+ },
+ "returnAddress": {
+ "description": "This container is needed if the seller is requesting that the buyer return the item. If this container is used, all relevant fields must be included, including fullName and primaryPhone.
Note: If the Dispute Reason is SIGNIFICANTLY_NOT_AS_DESCRIBED, returnAddress is required.",
+ "$ref": "#/components/schemas/ReturnAddress"
+ },
+ "revision": {
+ "type": "integer",
+ "description": "This integer value indicates the revision number of the payment dispute. This field is required. The current revision number for a payment dispute can be retrieved with the getPaymentDispute method. Each time an action is taken against a payment dispute, this integer value increases by 1.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used by the request payload of the contestPaymentDispute method."
+ },
+ "DeliveryCost": {
+ "type": "object",
+ "properties": {
+ "discountAmount": {
+ "description": "The amount of any shipping discount that has been applied to the line item. This container is returned only if a shipping discount applies to the line item.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "handlingCost": {
+ "description": "The amount of any handing cost that has been applied to the line item. This container is returned only if a handling cost applies to the line item.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "importCharges": {
+ "description": "The amount of any import charges applied to international shipping of the line item. This container is only returned if import charges apply to the line item.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "shippingCost": {
+ "description": "The total cost of shipping all units of the line item. This container is always returned even when the shipping cost is free, in which case the value field will show 0.0 (dollars).",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "shippingIntermediationFee": {
+ "description": "This field shows the fee due to eBay's international shipping provider for a line item that is being shipped through the Global Shipping Program.
This container is only returned for line items being shipped internationally through the Global Shipping Program, which is currently only supported in the US and UK marketplaces.
Note: The value returned for this field will always be 0.0 for line items sold in the UK marketplace.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type contains a breakdown of all costs associated with the fulfillment of a line item."
+ },
+ "DisputeAmount": {
+ "type": "object",
+ "properties": {
+ "convertedFromCurrency": {
+ "type": "string",
+ "description": "The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency.
This field is only returned if/when currency conversion was applied by eBay. For implementation help, refer to eBay API documentation"
+ },
+ "convertedFromValue": {
+ "type": "string",
+ "description": "The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field.
This field is only returned if/when currency conversion was applied by eBay."
+ },
+ "currency": {
+ "type": "string",
+ "description": "A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type.
Default: The currency of the authenticated user's country. For implementation help, refer to eBay API documentation"
+ },
+ "exchangeRate": {
+ "type": "string",
+ "description": "The exchange rate used for the monetary conversion. This field shows the exchange rate used to convert the dollar value in the value field from the dollar value in the convertedFromValue field.
This field is only returned if/when currency conversion was applied by eBay."
+ },
+ "value": {
+ "type": "string",
+ "description": "The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type."
+ }
+ },
+ "description": "This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable."
+ },
+ "DisputeEvidence": {
+ "type": "object",
+ "properties": {
+ "evidenceId": {
+ "type": "string",
+ "description": "Unique identifier of the evidential file set. Potentially, each evidential file set can have more than one file, that is why there is this file set identifier, and then an identifier for each file within this file set."
+ },
+ "evidenceType": {
+ "type": "string",
+ "description": "This enumeration value shows the type of evidential file provided. For implementation help, refer to eBay API documentation"
+ },
+ "files": {
+ "type": "array",
+ "description": "This array shows the name, ID, file type, and upload date for each provided file.",
+ "items": {
+ "$ref": "#/components/schemas/FileInfo"
+ }
+ },
+ "lineItems": {
+ "type": "array",
+ "description": "This array shows one or more order line items associated with the evidential document that has been provided.",
+ "items": {
+ "$ref": "#/components/schemas/OrderLineItems"
+ }
+ },
+ "providedDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when the seller provided a requested evidential document to eBay.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ },
+ "requestDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when eBay requested the evidential document from the seller in response to a payment dispute.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ },
+ "respondByDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when the seller was expected to provide a requested evidential document to eBay.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ },
+ "shipmentTracking": {
+ "type": "array",
+ "description": "This array shows the shipping carrier and shipment tracking number associated with each shipment package of the order. This array is returned under the evidence container if the seller has provided shipment tracking information as evidence to support PROOF_OF_DELIVERY for an INR-related payment dispute.",
+ "items": {
+ "$ref": "#/components/schemas/TrackingInfo"
+ }
+ }
+ },
+ "description": "This type is used by the evidence array that is returned in the getPaymentDispute response if one or more evidential documents are associated with the payment dispute. "
+ },
+ "DisputeSummaryResponse": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the getPaymentDisputeSummaries call request that produced the current page of the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "This value shows the maximum number of payment disputes that will appear on one page of the result set. The limit value can be passed in as a query parameter in the request, or if it is not used, it defaults to 200. If the value in the total field exceeds this limit value, there are multiple pages in the current result set.
Min: 1; Max: 200; Default: 200",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The getPaymentDisputeSummaries call URI to use if you wish to view the next page of the result set. For example, the following URI returns records 11 thru 20 from the collection of payment disputes:
path/payment_dispute_summary?limit=10&offset=10
This field is only returned if there is a next page of results to view based on the current input criteria."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "This integer value indicates the number of payment disputes skipped before listing the first payment dispute from the result set. The offset value can be passed in as a query parameter in the request, or if it is not used, it defaults to 0 and the first payment dispute of the result set is shown at the top of the response.",
+ "format": "int32"
+ },
+ "paymentDisputeSummaries": {
+ "type": "array",
+ "description": "Each payment dispute that matches the input criteria is returned under this array. If no payment disputes are found, an empty array is returned.",
+ "items": {
+ "$ref": "#/components/schemas/PaymentDisputeSummary"
+ }
+ },
+ "prev": {
+ "type": "string",
+ "description": "The getPaymentDisputeSummaries call URI to use if you wish to view the previous page of the result set. For example, the following URI returns records 1 thru 10 from the collection of payment disputes:
path/payment_dispute_summary?limit=10&offset=0
This field is only returned if there is a previous page of results to view based on the current input criteria."
+ },
+ "total": {
+ "type": "integer",
+ "description": "This integer value is the total number of payment disputes that matched the input criteria. If the total number of entries exceeds the value that was set for limit in the request payload, you will have to make multiple API calls to see all pages of the results set. This field is returned even if it is 0.",
+ "format": "int32"
+ }
+ },
+ "description": "This type defines the base response payload of the getPaymentDisputeSummaries method. Each payment dispute that matches the input criteria is returned under the paymentDisputeSummaries array."
+ },
+ "EbayCollectAndRemitTax": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "The monetary amount of the 'Collect and Remit' tax. This currently includes:
- US state-mandated sales tax
- Federal and Provincial Sales Tax in Canada
- 'Goods and Services' tax in Canada, Australia, New Zealand, and Jersey
- VAT collected for the UK, EU countries, Kazakhstan, and Belarus
- Sales & Service Tax (SST) in Malaysia
Note: If the corresponding taxType is STATE_SALES_TAX, PROVINCE_SALES_TAX, GST, VAT, or SST and the lineItems.taxes container also appears for this line item with the same tax amount, the order is subject to 'eBay Collect and Remit' tax. For orders that are subject to 'eBay Collect and Remit' tax, the tax amount in this field will be included in the lineItems.total, paymentSummary.payments.amount, paymentSummary.totalDueSeller, and pricingSummary.total fields.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "ebayReference": {
+ "description": "This container field describes the line-item level VAT tax details.
",
+ "$ref": "#/components/schemas/EbayTaxReference"
+ },
+ "taxType": {
+ "type": "string",
+ "description": "The type of tax and fees that eBay will collect and remit to the taxing or fee authority. See the TaxTypeEnum type definition for more information about each tax or fee type. For implementation help, refer to eBay API documentation"
+ },
+ "collectionMethod": {
+ "type": "string",
+ "description": "This field indicates the collection method used to collect the 'Collect and Remit' tax for the order. This field is always returned for orders subject to 'Collect and Remit' tax, and its value is always NET.
Note: Although the collectionMethod field is returned for all orders subject to 'Collect and Remit' tax, the collectionMethod field and the CollectionMethodEnum type are not currently of any practical use, although this field may have use in the future. If and when the logic of this field is changed, this note will be updated and a note will also be added to the Release Notes. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type contains information about the type and amount of tax that eBay will collect and remit to the state, province, country, or other taxing authority in the buyer's location, as required by that taxing authority.
'Collect and Remit' tax includes:- US state-mandated sales tax
- Federal and Provincial Sales Tax in Canada
- 'Goods and Services' tax in Canada, Australia, and New Zealand
- VAT collected for the UK and EU countries
"
+ },
+ "EbayCollectedCharges": {
+ "type": "object",
+ "properties": {
+ "ebayShipping": {
+ "description": "This container consists of costs related to eBay Shipping collected by eBay from the buyer of this order.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "charges": {
+ "type": "array",
+ "description": "This array shows any charges that eBay collects from the buyer.
Note: Currently, the only supported charge type is BUYER_PROTECTION.",
+ "items": {
+ "$ref": "#/components/schemas/Charge"
+ }
+ }
+ },
+ "description": "This type contains the breakdown of costs that are collected by eBay from the buyer."
+ },
+ "EbayFulfillmentProgram": {
+ "type": "object",
+ "properties": {
+ "fulfilledBy": {
+ "type": "string",
+ "description": "The value returned in this field indicates the party that is handling fulfillment of the order line item.
Valid value: EBAY"
+ }
+ },
+ "description": "This type is used to provide details about an order line item being fulfilled by eBay or an eBay fulfillment partner."
+ },
+ "EbayInternationalShipping": {
+ "type": "object",
+ "properties": {
+ "returnsManagedBy": {
+ "type": "string",
+ "description": "The value returned in this field indicates the party that is responsible for managing returns of the order line item.
Valid value: EBAY"
+ }
+ },
+ "description": "This type is used to provide details about an order line item being managed through eBay International Shipping."
+ },
+ "EbayShipping": {
+ "type": "object",
+ "properties": {
+ "shippingLabelProvidedBy": {
+ "type": "string",
+ "description": "This field contains the shipping label provider. If EBAY, this order is managed by eBay shipping and a free shipping label by eBay is downloadable by the seller via the eBay website."
+ }
+ },
+ "description": "This type contains information about the management of the shipping for the order."
+ },
+ "EbayTaxReference": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "This field value is returned to indicate the VAT tax type, which will vary by country/region. This string value will be one of the following:ABN: if this string is returned, the ID in the value field is an Australia tax IDDDG: if this string is returned, it indicates that tax has been collected and remitted for Digitally Delivered Goods (DDG)IOSS: if this string is returned, the ID in the value field is an eBay EU or UK IOSS numberIRD: if this string is returned, the ID in the value field is an eBay New Zealand tax IDSST: if this string is returned, the ID in the value field is an eBay Malaysia taxNumberOSS: if this string is returned, the ID in the value field is an eBay Germany VAT IDVOEC: if this string is returned, the ID in the value field is an eBay Norway tax ID
"
+ },
+ "value": {
+ "type": "string",
+ "description": "The value returned in this field is the VAT identifier number (VATIN), which will vary by country/region. This field will be returned if VAT tax is applicable for the order. The name field indicates the VAT tax type, which will vary by country/region: - ABN: eBay AU tax ID
- IOSS: eBay EU IOSS number / eBay UK IOSS number
- IRD: eBay NZ tax ID
- OSS: eBay DE VAT ID
- SST: eBay MY taxNumber
- VOEC: eBay NO number
"
+ }
+ },
+ "description": "This type describes the VAT tax details. The eBay VAT tax type and the eBay VAT identifier number will be returned if a VAT tax is applicable for the order.
"
+ },
+ "EbayVaultProgram": {
+ "type": "object",
+ "properties": {
+ "fulfillmentType": {
+ "type": "string",
+ "description": "This field specifies how an eBay vault order will be fulfilled. Supported options are:- Seller to Vault: the order will be shipped by the seller to an authenticator.
- Vault to Vault: the order will be shipped from an eBay vault to the buyer's vault.
- Vault to Buyer: the order will be shipped from an eBay vault to the buyer's shipping address.
For implementation help, refer to eBay API documentation"
+ }
}
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "33000": {
- "domain": "API_FULFILLMENT",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ },
+ "Error": {
+ "type": "object",
+ "properties": {
+ "category": {
+ "type": "string",
+ "description": "The context or source of this error or warning."
+ },
+ "domain": {
+ "type": "string",
+ "description": "The name of the domain containing the service or application. For example, sell is a domain."
+ },
+ "errorId": {
+ "type": "integer",
+ "description": "A positive integer that uniquely identifies the specific error condition that occurred. Your application can use these values as error code identifiers in your customized error-handling algorithms.",
+ "format": "int32"
+ },
+ "inputRefIds": {
+ "type": "array",
+ "description": "A list of one or more specific request elements (if any) associated with the error or warning. The format of these strings depends on the request payload format. For JSON, use JSONPath notation.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "longMessage": {
+ "type": "string",
+ "description": "An expanded version of the message field.
Maximum length: 200 characters"
+ },
+ "message": {
+ "type": "string",
+ "description": "A message about the error or warning which is device agnostic and readable by end users and application developers. It explains what the error or warning is, and how to fix it (in a general sense). If applicable, the value is localized to the end user's requested locale.
Maximum length: 50 characters"
+ },
+ "outputRefIds": {
+ "type": "array",
+ "description": "A list of one or more specific response elements (if any) associated with the error or warning. The format of these strings depends on the request payload format. For JSON, use JSONPath notation.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "parameters": {
+ "type": "array",
+ "description": "Contains a list of name-value pairs that provide additional information concerning this error or warning. Each item in the list is an input parameter that contributed to the error or warning condition.",
+ "items": {
+ "$ref": "#/components/schemas/ErrorParameter"
+ }
+ },
+ "subdomain": {
+ "type": "string",
+ "description": "The name of the domain's subsystem or subdivision. For example, fulfillment is a subdomain in the sell domain."
+ }
+ },
+ "description": "This type contains a error or warning related to a call request. "
+ },
+ "ErrorParameter": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "This is the name of input field that caused an issue with the call request."
+ },
+ "value": {
+ "type": "string",
+ "description": "This is the actual value that was passed in for the element specified in the name field."
+ }
+ },
+ "description": "This type contains the name and value of an input parameter that contributed to a specific error or warning condition."
+ },
+ "EvidenceRequest": {
+ "type": "object",
+ "properties": {
+ "evidenceId": {
+ "type": "string",
+ "description": "Unique identifier of the evidential file set. Potentially, each evidential file set can have more than one file, that is why there is this file set identifier, and then an identifier for each file within this file set."
+ },
+ "evidenceType": {
+ "type": "string",
+ "description": "This enumeration value shows the type of evidential document provided. For implementation help, refer to eBay API documentation"
+ },
+ "lineItems": {
+ "type": "array",
+ "description": "This array shows one or more order line items associated with the evidential document that has been provided.",
+ "items": {
+ "$ref": "#/components/schemas/OrderLineItems"
+ }
+ },
+ "requestDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when eBay requested the evidential document from the seller in response to a payment dispute.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ },
+ "respondByDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when the seller is expected to provide a requested evidential document to eBay.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ }
+ },
+ "description": "This type is used by the evidenceRequests array that is returned in the getPaymentDispute response if one or more evidential documents are being requested to help resolve the payment dispute."
+ },
+ "ExtendedContact": {
+ "type": "object",
+ "properties": {
+ "companyName": {
+ "type": "string",
+ "description": "The company name associated with the buyer or eBay shipping partner. This field is only returned if defined/applicable to the buyer or eBay shipping partner."
+ },
+ "contactAddress": {
+ "description": "This container shows the shipping address of the buyer or eBay shipping partner.",
+ "$ref": "#/components/schemas/Address"
+ },
+ "email": {
+ "type": "string",
+ "description": "This field contains the email address of the buyer. This address will be returned for up to 14 days from order creation. If an order is more than 14 days old, no address is returned.
Note: If returned, this field contains the email address of the buyer, even for Global Shipping Program shipments.
The email will not be returned for any order that is more than 90 days old."
+ },
+ "fullName": {
+ "type": "string",
+ "description": "The full name of the buyer or eBay shipping partner.
Note: The fullName will not be returned for any order that is more than 90 days old."
+ },
+ "primaryPhone": {
+ "description": "The primary telephone number of the buyer or eBay shipping partner.
Note: The primaryPhone will not be returned for any order that is more than 90 days old.",
+ "$ref": "#/components/schemas/PhoneNumber"
+ }
+ },
+ "description": "This type contains shipping and contact information for a buyer or an eBay shipping partner."
+ },
+ "FileEvidence": {
+ "type": "object",
+ "properties": {
+ "fileId": {
+ "type": "string",
+ "description": "This field is used to identify the evidence file to be uploaded to the evidence set.
This file is created with the uploadEvidenceFile method and can be retrieved using the getPaymentDisputes method."
+ }
+ },
+ "description": "This type is used to store the unique identifier of an evidence file. Evidence files are used by seller to contest a payment dispute."
+ },
+ "FileInfo": {
+ "type": "object",
+ "properties": {
+ "fileId": {
+ "type": "string",
+ "description": "The unique identifier of the evidence file."
+ },
+ "fileType": {
+ "type": "string",
+ "description": "The type of file uploaded. Supported file extensions are .JPEG, .JPG, and .PNG., and maximum file size allowed is 1.5 MB."
+ },
+ "name": {
+ "type": "string",
+ "description": "The seller-provided name of the evidence file."
+ },
+ "uploadedDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when the seller uploaded the evidential document to eBay.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ }
+ },
+ "description": "This type is used by the files array, which shows the name, ID, file type, and upload date for each provided evidential file."
+ },
+ "FulfillmentStartInstruction": {
+ "type": "object",
+ "properties": {
+ "appointment": {
+ "description": "This container provides information used by the installation provider concerning appointment details selected by the buyer.",
+ "$ref": "#/components/schemas/AppointmentDetails"
+ },
+ "ebaySupportedFulfillment": {
+ "type": "boolean",
+ "description": "This field is only returned if its value is true and indicates that the fulfillment will be shipped via eBay's Global Shipping Program, eBay International Shipping, or the Authenticity Guarantee service program.
For more information, see the Global Shipping Program help topic."
+ },
+ "finalDestinationAddress": {
+ "description": "This container is only returned if the value of ebaySupportedFulfillment field is true.
This is the final destination address for a Global Shipping Program shipment or an eBay International Shipping shipment, which is usually the recipient's home. Sellers should not ship directly to this address; instead they should ship this package to their international shipping provider's domestic warehouse. The international shipping provider is responsible for delivery to the final destination address.
For more information, see Addressing Shipments. Note: For Authenticity Guarantee program shipment, this is the address of the authenticator's warehouse. The authenticator is responsible for delivery to the buyer shipping address.
",
+ "$ref": "#/components/schemas/Address"
+ },
+ "fulfillmentInstructionsType": {
+ "type": "string",
+ "description": "The enumeration value returned in this field indicates the method of fulfillment that will be used to deliver this set of line items (this package) to the buyer. This field will have a value of SHIP_TO if the ebaySupportedFulfillment field is returned with a value of true. See the FulfillmentInstructionsType definition for more information about different fulfillment types. For implementation help, refer to eBay API documentation"
+ },
+ "maxEstimatedDeliveryDate": {
+ "type": "string",
+ "description": "This is the estimated latest date that the fulfillment will be completed. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned ifthe value of the fulfillmentInstructionsType field is DIGITAL or PREPARE_FOR_PICKUP.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "minEstimatedDeliveryDate": {
+ "type": "string",
+ "description": "This is the estimated earliest date that the fulfillment will be completed. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned if the value of the fulfillmentInstructionsType field is DIGITAL or PREPARE_FOR_PICKUP.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "pickupStep": {
+ "description": "This container is only returned for In-Store Pickup orders, and it indicates the specific merchant's store where the buyer will pick up the order. The In-Store Pickup feature is supported in the US, Canada, UK, Germany, and Australia marketplaces.",
+ "$ref": "#/components/schemas/PickupStep"
+ },
+ "shippingStep": {
+ "description": "This container consists of shipping information for this fulfillment, including the shipping carrier, the shipping service option, and the shipment destination. This container is not returned if the value of the fulfillmentInstructionsType field is DIGITAL, or for In-Store Pickup orders.
For Click and Collect orders, the shipping destination will be a brick-and-mortar store where the buyer will pick up the order.",
+ "$ref": "#/components/schemas/ShippingStep"
+ }
+ },
+ "description": "This type contains a set of specifications for processing a fulfillment of an order, including the type of fulfillment, shipping carrier and service, addressing details, and estimated delivery window. These instructions are derived from the buyer's and seller's eBay account preferences, the listing parameters, and the buyer's checkout selections. The seller can use them as a starting point for packaging, addressing, and shipping the order."
+ },
+ "GiftDetails": {
+ "type": "object",
+ "properties": {
+ "message": {
+ "type": "string",
+ "description": "This field contains the gift message from the buyer to the gift recipient. This field is only returned if the buyer of the gift included a message for the gift.
Note: The message will not be returned for any order that is more than 90 days old."
+ },
+ "recipientEmail": {
+ "type": "string",
+ "description": "The email address of the gift recipient. The seller will send the digital gift card to this email address.
Note: The recipientEmail will not be returned for any order that is more than 90 days old."
+ },
+ "senderName": {
+ "type": "string",
+ "description": "The name of the buyer, which will appear on the email that is sent to the gift recipient.
Note: The senderName will not be returned for any order that is more than 90 days old."
+ }
+ },
+ "description": "This type contains information about a digital gift card line item that was purchased as a gift and sent to the recipient by email.
Note: GiftDetails will not be returned for any order that is more than 90 days old."
+ },
+ "InfoFromBuyer": {
+ "type": "object",
+ "properties": {
+ "contentOnHold": {
+ "type": "boolean",
+ "description": "When the value of this field is true it indicates that the buyer's note regarding the payment dispute (i.e., the buyerProvided.note field,) is on hold. When this is the case, the buyerProvided.note field will not be returned.
When the value of this field is false, it is not returned."
+ },
+ "note": {
+ "type": "string",
+ "description": "This field shows any note that was left by the buyer in regard to the dispute."
+ },
+ "returnShipmentTracking": {
+ "type": "array",
+ "description": "This array shows shipment tracking information for one or more shipping packages being returned to the buyer after a payment dispute.",
+ "items": {
+ "$ref": "#/components/schemas/TrackingInfo"
+ }
+ }
+ },
+ "description": "This container is returned if the buyer is returning one or more line items in an order that is associated with the payment dispute, and that buyer has provided return shipping tracking information and/or a note about the return."
+ },
+ "IssueRefundRequest": {
+ "type": "object",
+ "properties": {
+ "reasonForRefund": {
+ "type": "string",
+ "description": "The enumeration value passed into this field indicates the reason for the refund. One of the defined enumeration values in the ReasonForRefundEnum type must be used.
This field is required, and it is highly recommended that sellers use the correct refund reason, especially in the case of a buyer-requested cancellation or 'buyer remorse' return to indicate that there was nothing wrong with the item(s) or with the shipment of the order.
Note: If issuing refunds for more than one order line item, keep in mind that the refund reason must be the same for each of the order line items. If the refund reason is different for one or more order line items in an order, the seller would need to make separate issueRefund calls, one for each refund reason. For implementation help, refer to eBay API documentation"
+ },
+ "comment": {
+ "type": "string",
+ "description": "This free-text field allows the seller to clarify why the refund is being issued to the buyer.
Max Length: 100"
+ },
+ "refundItems": {
+ "type": "array",
+ "description": "The refundItems array is only required if the seller is issuing a refund for one or more individual order line items in a multiple line item order. Otherwise, the seller just uses the orderLevelRefundAmount container to specify the amount of the refund for the entire order.",
+ "items": {
+ "$ref": "#/components/schemas/RefundItem"
+ }
+ },
+ "orderLevelRefundAmount": {
+ "description": "This container is used to specify the amount of the refund for the entire order. If a seller wants to issue a refund for an individual line item within a multiple line item order, the seller would use the refundItems array instead.",
+ "$ref": "#/components/schemas/SimpleAmount"
+ }
+ },
+ "description": "The base type used by the request payload of the issueRefund method."
+ },
+ "ItemLocation": {
+ "type": "object",
+ "properties": {
+ "countryCode": {
+ "type": "string",
+ "description": "The two-letter ISO 3166 code representing the country of the address. For implementation help, refer to eBay API documentation"
+ },
+ "location": {
+ "type": "string",
+ "description": "Indicates the geographical location of the item (along with the values in the countryCode and postalCode fields).
Note: If the item is shipped from a fulfillment center location through the Multi-Warehouse Program, this field will return the geographical location of the fulfillment center closest to the buyer.
This field provides city, province, state, or similar information."
+ },
+ "postalCode": {
+ "type": "string",
+ "description": "The postal code of the address."
+ }
+ },
+ "description": "This type describes the physical location of an order."
+ },
+ "LegacyReference": {
+ "type": "object",
+ "properties": {
+ "legacyItemId": {
+ "type": "string",
+ "description": "The unique identifier of a listing.
This value can be found in the Transaction container in the response of the getOrder call of the Trading API.
Note: Both legacyItemId and legacyTransactionId are needed to identify an order line item. "
+ },
+ "legacyTransactionId": {
+ "type": "string",
+ "description": "The unique identifier of a sale/transaction in legacy/Trading API format. A 'transaction ID' is created once a buyer purchases a 'Buy It Now' item or if an auction listing ends with a winning bidder.
This value can be found in the Transaction container in the response of the getOrder call of the Trading API.
Note: Both legacyItemId and legacyTransactionId are needed to identify an order line item. "
+ }
+ },
+ "description": "Type defining the legacyReference container. This container is needed if the seller is issuing a refund for an individual order line item, and wishes to use an item ID and transaction ID to identify the order line item."
+ },
+ "LineItem": {
+ "type": "object",
+ "properties": {
+ "appliedPromotions": {
+ "type": "array",
+ "description": "This array contains information about one or more sales promotions or discounts applied to the line item. It is always returned, but will be returned as an empty array if no special sales promotions or discounts apply to the order line item.",
+ "items": {
+ "$ref": "#/components/schemas/AppliedPromotion"
+ }
+ },
+ "compatibilityProperties": {
+ "type": "array",
+ "description": "This array is only returned for a Parts & Accessory item, and identifies the buyer's motor vehicle that is compatible with the part or accessory.",
+ "items": {
+ "$ref": "#/components/schemas/Property"
+ }
+ },
+ "deliveryCost": {
+ "description": "This container consists of a breakdown of all costs associated with the fulfillment of the line item.",
+ "$ref": "#/components/schemas/DeliveryCost"
+ },
+ "discountedLineItemCost": {
+ "description": "The cost of the line item after applying any discounts. This container is only returned if the order line item was discounted through a promotion.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "ebayCollectAndRemitTaxes": {
+ "type": "array",
+ "description": "This container will be returned if the order line item is subject to a 'Collect and Remit' tax that eBay will collect and remit to the proper taxing authority on the buyer's behalf.
'Collect and Remit' tax includes:- US state-mandated sales tax
- Federal and Provincial Sales Tax in Canada
- 'Goods and Services' tax in Canada, Australia, New Zealand, and Jersey
- VAT collected for the UK, EU countries, Kazakhstan, and Belarus
- Sales & Service Tax (SST) in Malaysia
The amount of this tax is shown in the amount field, and the type of tax is shown in the taxType field.
eBay will display the tax type and amount during checkout in accordance with the buyer's address, and handle collection and remittance of the tax without requiring the seller to take any action.",
+ "items": {
+ "$ref": "#/components/schemas/EbayCollectAndRemitTax"
+ }
+ },
+ "ebayCollectedCharges": {
+ "description": "This container consists of a breakdown of costs that are collected by eBay from the buyer for this order.
Note: Currently, this container is returned only if eBay is directly charging the buyer for eBay shipping.",
+ "$ref": "#/components/schemas/EbayCollectedCharges"
+ },
+ "giftDetails": {
+ "description": "This container consists of information that is needed by the seller to send a digital gift card to the buyer, or recipient of the digital gift card. This container is only returned and applicable for digital gift card line items.",
+ "$ref": "#/components/schemas/GiftDetails"
+ },
+ "itemLocation": {
+ "description": "This container field describes the physical location of the order line item.
Note: If the item is shipped from a fulfillment center location through the Multi-Warehouse Program, this container will return the location details of the fulfillment center closest to the buyer.",
+ "$ref": "#/components/schemas/ItemLocation"
+ },
+ "legacyItemId": {
+ "type": "string",
+ "description": "The eBay-generated legacy listing item ID of the listing. Note that the unique identifier of a listing in REST-based APIs is called the listingId instead."
+ },
+ "legacyVariationId": {
+ "type": "string",
+ "description": "The unique identifier of a single variation within a multiple-variation listing. This field is only returned if the line item purchased was from a multiple-variation listing."
+ },
+ "lineItemCost": {
+ "description": "The selling price of the line item before applying any discounts. The value of this field is calculated by multiplying the single unit price by the number of units purchased (value of the quantity field).",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "lineItemFulfillmentInstructions": {
+ "description": "This container consists of information related to shipping dates and expectations, including the 'ship-by date' and expected delivery windows that are based on the seller's stated handling time and the shipping service option that will be used. These fields provide guidance on making sure expected delivery dates are made, whether the order is a eBay Guaranteed Delivery order or a non-guaranteed delivery order.",
+ "$ref": "#/components/schemas/LineItemFulfillmentInstructions"
+ },
+ "lineItemFulfillmentStatus": {
+ "type": "string",
+ "description": "This enumeration value indicates the current fulfillment status of the line item. For implementation help, refer to eBay API documentation"
+ },
+ "lineItemId": {
+ "type": "string",
+ "description": "This is the unique identifier of an eBay order line item. This field is created as soon as there is a commitment to buy from the seller."
+ },
+ "linkedOrderLineItems": {
+ "type": "array",
+ "description": "An array of one or more line items related to the corresponding order, but not a part of that order. Details include the order ID, line item ID, and title of the linked line item, the seller of that item, item specifics, estimated delivery times, and shipment tracking (if available).",
+ "items": {
+ "$ref": "#/components/schemas/LinkedOrderLineItem"
+ }
+ },
+ "listingMarketplaceId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay marketplace where the line item was listed. For implementation help, refer to eBay API documentation"
+ },
+ "properties": {
+ "description": "Contains information about the eBay programs, if any, under which the line item was listed.",
+ "$ref": "#/components/schemas/LineItemProperties"
+ },
+ "purchaseMarketplaceId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay marketplace where the line item was listed. Often, the listingMarketplaceId and the purchaseMarketplaceId identifier are the same, but there are occasions when an item will surface on multiple eBay marketplaces. For implementation help, refer to eBay API documentation"
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "The number of units of the line item in the order. These are represented as a group by a single lineItemId.",
+ "format": "int32"
+ },
+ "refunds": {
+ "type": "array",
+ "description": "This array is always returned, but is returned as an empty array unless the seller has submitted a partial or full refund to the buyer for the order. If a refund has occurred, the refund amount and refund date will be shown for each refund.",
+ "items": {
+ "$ref": "#/components/schemas/LineItemRefund"
+ }
+ },
+ "sku": {
+ "type": "string",
+ "description": "Seller-defined Stock-Keeping Unit (SKU). This inventory identifier must be unique within the seller's eBay inventory. SKUs are optional when listing in the legacy/Trading API system, but SKUs are required when listing items through the Inventory API model."
+ },
+ "soldFormat": {
+ "type": "string",
+ "description": "The eBay listing type of the line item. The most common listing types are AUCTION and FIXED_PRICE. For implementation help, refer to eBay API documentation"
+ },
+ "taxes": {
+ "type": "array",
+ "description": "Contains a list of taxes applied to the line item, if any. This array is always returned, but will be returned as empty if no taxes are applicable to the line item.",
+ "items": {
+ "$ref": "#/components/schemas/Tax"
+ }
+ },
+ "title": {
+ "type": "string",
+ "description": "The title of the listing.
Note: The Item ID value for the listing will be returned in this field instead of the actual title if this particular listing is on-hold due to an eBay policy violation."
+ },
+ "total": {
+ "description": "This is the total price that the buyer must pay for the line item after all costs (item cost, delivery cost, taxes,) are added, minus any discounts and/or promotions.
Note: For orders that are subject to 'eBay Collect and Remit' tax, the 'Collect and Remit' tax amount for the order will be included in this total value only when the fieldGroups query parameter is set to TAX_BREAKDOWN. If the fieldGroups query parameter is not set to TAX_BREAKDOWN, 'Collect and Remit' will not be added into this total value.
To determine if 'Collect and Remit' taxes were added into this total value, the user can check for the corresponding lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is in this amount:STATE_SALES_TAX: US state-mandated sales taxPROVINCE_SALES_TAX: Provincial Sales Tax in CanadaGST: 'Goods and Services' tax in Canada, Australia, and New ZealandVAT: VAT collected for UK and EU countries
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "variationAspects": {
+ "type": "array",
+ "description": "An array of aspect name-value pairs that identifies the specific variation of a multi-variation listing. This array can contain multiple name-value pairs, such as color:blue and size:large, and will only be returned for orders created from a multiple-variation listing.",
+ "items": {
+ "$ref": "#/components/schemas/NameValuePair"
+ }
+ }
+ },
+ "description": "This type contains the details of each line item in an order."
+ },
+ "LineItemFulfillmentInstructions": {
+ "type": "object",
+ "properties": {
+ "guaranteedDelivery": {
+ "type": "boolean",
+ "description": "Although this field is still returned, it can be ignored since eBay Guaranteed Delivery is no longer a supported feature on any marketplace. This field may get removed from the schema in the future."
+ },
+ "maxEstimatedDeliveryDate": {
+ "type": "string",
+ "description": "The estimated latest date and time that the buyer can expect to receive the line item based on the seller's stated handling time and the transit times of the available shipping service options. The seller must pay extra attention to this date, as a failure to deliver by this date/time can result in a 'Late shipment' seller defect, and can affect seller level and Top-Rated Seller status. In addition to the seller defect, buyers will be eligible for a shipping cost refund, and will also be eligible to return the item for a full refund (with no return shipping charge) if they choose.
Note: This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "minEstimatedDeliveryDate": {
+ "type": "string",
+ "description": "The estimated earliest date and time that the buyer can expect to receive the line item based on the seller's stated handling time and the transit times of the available shipping service options.
Note: This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "shipByDate": {
+ "type": "string",
+ "description": "The latest date and time by which the seller should ship line item in order to meet the expected delivery window. This timestamp will be set by eBay based on time of purchase and the seller's stated handling time. The seller must pay extra attention to this date, as a failure to physically ship the line item by this date/time can result in a 'Late shipment' seller defect, and can affect seller level and Top-Rated Seller status. In addition to the seller defect, buyers will be eligible for a shipping cost refund, and will also be eligible to return the item for a full refund (with no return shipping charge) if they choose.
Note: This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ }
+ },
+ "description": "This type contains the specifications for processing the fulfillment of a line item, including the handling window and the delivery window. These fields provide guidance for eBay Guaranteed Delivery as well as for non-guaranteed delivery."
+ },
+ "LineItemProperties": {
+ "type": "object",
+ "properties": {
+ "buyerProtection": {
+ "type": "boolean",
+ "description": "A value of true indicates that the line item is covered by eBay's Buyer Protection program."
+ },
+ "fromBestOffer": {
+ "type": "boolean",
+ "description": "This field is only returned if true and indicates that the purchase occurred by the buyer and seller mutually agreeing on a Best Offer amount. The Best Offer feature can be set up for any listing type, but if this feature is set up for an auction listing, it will no longer be available once a bid has been placed on the listing."
+ },
+ "soldViaAdCampaign": {
+ "type": "boolean",
+ "description": "This field is only returned if true and indicates that the line item was sold as a result of a seller's ad campaign."
+ }
+ },
+ "description": "This type contains information about the eBay programs under which a line item was listed and sold."
+ },
+ "LineItemReference": {
+ "type": "object",
+ "properties": {
+ "lineItemId": {
+ "type": "string",
+ "description": "This is the unique identifier of the eBay order line item that is part of the shipping fulfillment.
Line item Ids can be found in the lineItems.lineItemId field of the getOrders response."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "This is the number of lineItems associated with the trackingNumber specified by the seller. This must be a whole number greater than zero (0).
Default: 1",
+ "format": "int32"
+ }
+ },
+ "description": "This type identifies the line item and quantity of that line item that comprises one fulfillment, such as a shipping package."
+ },
+ "LineItemRefund": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "This field shows the refund amount for a line item. This field is only returned if the buyer is due a refund for the line item.
Note: The refund amount shown is the seller's net amount received from the sale/transaction. eBay-collected tax will not be included in this amount, so the actual amount of the buyer's refund may be higher than this value.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "refundDate": {
+ "type": "string",
+ "description": "The date and time that the refund was issued for the line item. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the refund has been issued.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "refundId": {
+ "type": "string",
+ "description": "Unique identifier of a refund that was initiated for an order's line item through the issueRefund method. If the issueRefund method was used to issue a refund at the order level, this identifier is returned at the order level instead (paymentSummary.refunds.refundId field).
A refundId value is returned in the response of the issueRefund method, and this same value will be returned in the getOrder and getOrders responses for pending and completed refunds."
+ },
+ "refundReferenceId": {
+ "type": "string",
+ "description": "This field is reserved for internal or future use."
+ }
+ },
+ "description": "This type contains refund information for a line item."
+ },
+ "LinkedOrderLineItem": {
+ "type": "object",
+ "properties": {
+ "lineItemAspects": {
+ "type": "array",
+ "description": "This array contains the complete set of items aspects for the linked line item. For example:
\"lineItemAspects\": [
{
\"name\": \"Tire Type\",
\"value\": \"All Season\"
},
...
{
\"name\": \"Car Type\",
\"value\": \"Performance\"
}
]
Note: All item specifics for the listing are returned. The name/value pairs returned are in the language of the linked line item's listing site, which may vary from the seller's language.",
+ "items": {
+ "$ref": "#/components/schemas/NameValuePair"
+ }
+ },
+ "lineItemId": {
+ "type": "string",
+ "description": "The unique identifier of the linked order line item."
+ },
+ "maxEstimatedDeliveryDate": {
+ "type": "string",
+ "description": "The end of the date range in which the linked line item is expected to be delivered to the shipping address."
+ },
+ "minEstimatedDeliveryDate": {
+ "type": "string",
+ "description": "The beginning of the date range in which the linked line item is expected to be delivered to the shipping address."
+ },
+ "orderId": {
+ "type": "string",
+ "description": "The unique identifier of the order to which the linked line item belongs."
+ },
+ "sellerId": {
+ "type": "string",
+ "description": "The eBay user ID of the seller who sold the linked line item. For example, the user ID of the tire seller."
+ },
+ "shipments": {
+ "type": "array",
+ "description": "An array containing any shipment tracking information available for the linked line item.",
+ "items": {
+ "$ref": "#/components/schemas/TrackingInfo"
+ }
+ },
+ "title": {
+ "type": "string",
+ "description": "The listing title of the linked line item.
Note: The Item ID value for the listing will be returned in this field instead of the actual title if this particular listing is on-hold due to an eBay policy violation."
+ }
+ },
+ "description": "This type contains data on a line item that is related to, but not a part of the order."
+ },
+ "MonetaryTransaction": {
+ "type": "object",
+ "properties": {
+ "date": {
+ "type": "string",
+ "description": "This timestamp indicates when the monetary transaction occurred. A date is returned for all monetary transactions.
The following format is used: YYYY-MM-DDTHH:MM:SS.SSSZ. For example, 2015-08-04T19:09:02.768Z."
+ },
+ "type": {
+ "type": "string",
+ "description": "This enumeration value indicates whether the monetary transaction is a charge or a credit to the seller. For implementation help, refer to eBay API documentation"
+ },
+ "reason": {
+ "type": "string",
+ "description": "This enumeration value indicates the reason for the monetary transaction. For implementation help, refer to eBay API documentation"
+ },
+ "amount": {
+ "description": "The amount involved in the monetary transaction. For active cross-border trade orders, the currency conversion and exchangeRate fields will be displayed as well.",
+ "$ref": "#/components/schemas/DisputeAmount"
+ }
+ },
+ "description": "This type is used to provide details about one or more monetary transactions that occur as part of a payment dispute."
+ },
+ "NameValuePair": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "The text representing the name of the aspect for the name-value pair. For example, color, or Tire Type."
+ },
+ "value": {
+ "type": "string",
+ "description": "The value of the aspect for the name-value pair. For example, red, or All Season."
+ }
+ },
+ "description": "This type contains the name-value specifics of a multi-variation listing (variationAspects) or the name-value specifics for all item aspects of a linked line item (linkedOrderLineItems)."
+ },
+ "Order": {
+ "type": "object",
+ "properties": {
+ "buyer": {
+ "description": "This container consists of information about the order's buyer. At this time, only the buyer's eBay user ID is returned, but it's possible that more buyer information can be added to this container in the future.",
+ "$ref": "#/components/schemas/Buyer"
+ },
+ "buyerCheckoutNotes": {
+ "type": "string",
+ "description": "This field contains any comments that the buyer left for the seller about the order during checkout process. This field is only returned if a buyer left comments at checkout time. "
+ },
+ "cancelStatus": {
+ "description": "This container consists of order cancellation information if a cancel request has been made. This container is always returned, and if no cancel request has been made, the cancelState field is returned with a value of NONE_REQUESTED, and an empty cancelRequests array is also returned.",
+ "$ref": "#/components/schemas/CancelStatus"
+ },
+ "creationDate": {
+ "type": "string",
+ "description": "The date and time that the order was created. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "ebayCollectAndRemitTax": {
+ "type": "boolean",
+ "description": "This field is only returned if true, and indicates that eBay will collect tax (US state-mandated sales tax, Federal and Provincial Sales Tax in Canada, 'Goods and Services' tax in Canada, Australia, and New Zealand, and VAT collected for UK and EU countries,) for at least one line item in the order, and remit the tax to the taxing authority of the buyer's residence. If this field is returned, the seller should search for one or more ebayCollectAndRemitTaxes containers at the line item level to get more information about the type of tax and the amount."
+ },
+ "fulfillmentHrefs": {
+ "type": "array",
+ "description": "This array contains a list of one or more getShippingFulfillment call URIs that can be used to retrieve shipping fulfillments that have been set up for the order.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "fulfillmentStartInstructions": {
+ "type": "array",
+ "description": "This container consists of a set of specifications for fulfilling the order, including the type of fulfillment, shipping carrier and service, shipping address, and estimated delivery window. These instructions are derived from the buyer's and seller's eBay account preferences, the listing parameters, and the buyer's checkout selections. The seller can use them as a starting point for packaging, addressing, and shipping the order.
Note: Although this container is presented as an array, it currently returns only one set of fulfillment specifications. Additional array members will be supported in future functionality.",
+ "items": {
+ "$ref": "#/components/schemas/FulfillmentStartInstruction"
+ }
+ },
+ "lastModifiedDate": {
+ "type": "string",
+ "description": "The date and time that the order was last modified. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "lineItems": {
+ "type": "array",
+ "description": "This array contains the details for all line items that comprise the order.",
+ "items": {
+ "$ref": "#/components/schemas/LineItem"
+ }
+ },
+ "orderFulfillmentStatus": {
+ "type": "string",
+ "description": "The degree to which fulfillment of the order is complete. See the OrderFulfillmentStatus type definition for more information about each possible fulfillment state. For implementation help, refer to eBay API documentation"
+ },
+ "orderId": {
+ "type": "string",
+ "description": "The unique identifier of the order. This field is always returned."
+ },
+ "orderPaymentStatus": {
+ "type": "string",
+ "description": "The enumeration value returned in this field indicates the current payment status of an order, or in case of a refund request, the current status of the refund. See the OrderPaymentStatusEnum type definition for more information about each possible payment/refund state. For implementation help, refer to eBay API documentation"
+ },
+ "paymentSummary": {
+ "description": "This container consists of detailed payment information for the order, including buyer payment for the order, refund information (if applicable), and seller payment holds (if applicable).",
+ "$ref": "#/components/schemas/PaymentSummary"
+ },
+ "pricingSummary": {
+ "description": "This container consists of a summary of cumulative costs and charges for all line items of an order, including item price, price adjustments, sales taxes, delivery costs, and order discounts.",
+ "$ref": "#/components/schemas/PricingSummary"
+ },
+ "program": {
+ "description": "This container is returned for orders that are eligible for eBay's Authenticity Guarantee service. The seller ships Authenticity Guarantee service items to the authentication partner instead of the buyer. The authenticator address is found in the fulfillmentStartInstructions.shippingStep.shipTo container. If the item is successfully authenticated, the authenticator will ship the item to the buyer.",
+ "$ref": "#/components/schemas/Program"
+ },
+ "salesRecordReference": {
+ "type": "string",
+ "description": "An eBay-generated identifier that is used to identify and manage orders through the Selling Manager and Selling Manager Pro tools. This order identifier can also be found on the Orders grid page and in the Sales Record pages in Seller Hub. A salesRecordReference number is only generated and returned at the order level, and not at the order line item level.
In cases where the seller does not have a Selling Manager or Selling Manager Pro subscription nor access to Seller Hub, this field may not be returned."
+ },
+ "sellerId": {
+ "type": "string",
+ "description": "The unique eBay user ID of the seller who sold the order."
+ },
+ "totalFeeBasisAmount": {
+ "description": "This is the cumulative base amount used to calculate the final value fees for each order. The final value fees are deducted from the seller payout associated with the order. Final value fees are calculated as a percentage of order cost (item cost + shipping cost) and the percentage rate can vary by eBay category. ",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "totalMarketplaceFee": {
+ "description": "This is the cumulative fees accrued for the order and deducted from the seller payout.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type contains the details of an order, including information about the buyer, order history, shipping fulfillments, line items, costs, payments, and order fulfillment status."
+ },
+ "OrderLineItems": {
+ "type": "object",
+ "properties": {
+ "itemId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay listing associated with the order."
+ },
+ "lineItemId": {
+ "type": "string",
+ "description": "The unique identifier of the line item within the order."
+ }
+ },
+ "description": "This type is used by the lineItems array that is used to identify one or more line items in the order with the payment dispute."
+ },
+ "OrderRefund": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "This field shows the refund amount for an order. This container is always returned for each refund.
Note: The refund amount shown is the seller's net amount received from the sale/transaction. eBay-collected tax will not be included in this amount, so the actual amount of the buyer's refund may be higher than this value.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "refundDate": {
+ "type": "string",
+ "description": "The date and time that the refund was issued. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the refund has been issued.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "refundId": {
+ "type": "string",
+ "description": "Unique identifier of a refund that was initiated for an order through the issueRefund method. If the issueRefund method was used to issue one or more refunds at the line item level, these refund identifiers are returned at the line item level instead (lineItems.refunds.refundId field).
A refundId value is returned in the response of the issueRefund method, and this same value will be returned in the getOrders and getOrders responses for pending and completed refunds. For other refunds, see the refundReferenceId field."
+ },
+ "refundReferenceId": {
+ "type": "string",
+ "description": "The eBay-generated unique identifier for the refund. This field is not returned until the refund has been issued."
+ },
+ "refundStatus": {
+ "type": "string",
+ "description": "This enumeration value indicates the current status of the refund to the buyer. This container is always returned for each refund. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type contains information about a refund issued for an order. This does not include line item level refunds."
+ },
+ "OrderSearchPagedCollection": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the getOrders call request that produced the current page of the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The maximum number of orders returned per page of the result set. The limit value can be passed in as a query parameter, or if omitted, its value defaults to 50.
Note: If this is the last or only page of the result set, the page may contain fewer orders than the limit value. To determine the number of pages in a result set, divide the total value (total number of orders matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total orders) and the limit value was 50 (show 50 orders per page), the total number of pages in the result set is three, so the seller would have to make three separate getOrders calls to view all orders matching the input criteria. Default: 50",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The getOrders call URI to use if you wish to view the next page of the result set. For example, the following URI returns records 41 thru 50 from the collection of orders:
path/order?limit=10&offset=40
This field is only returned if there is a next page of results to view based on the current input criteria.
"
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "orders": {
+ "type": "array",
+ "description": "This array contains one or more orders that are part of the current result set, that is controlled by the input criteria. The details of each order include information about the buyer, order history, shipping fulfillments, line items, costs, payments, and order fulfillment status.
By default, orders are returned according to creation date (oldest to newest), but the order will vary according to any filter that is set in request.",
+ "items": {
+ "$ref": "#/components/schemas/Order"
+ }
+ },
+ "prev": {
+ "type": "string",
+ "description": "The getOrders call URI for the previous result set. For example, the following URI returns orders 21 thru 30 from the collection of orders:
path/order?limit=10&offset=20
This field is only returned if there is a previous page of results to view based on the current input criteria."
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of orders in the results set based on the current input criteria.
Note: If no orders are found, this field is returned with a value of 0.",
+ "format": "int32"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "This array is returned if one or more errors or warnings occur with the call request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type contains the specifications for the collection of orders that match the search or filter criteria of a getOrders call. The collection is grouped into a result set, and based on the query parameters that are set (including the limit and offset parameters), the result set may included multiple pages, but only one page of the result set can be viewed at a time."
+ },
+ "Payment": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "The amount that seller receives for the order via the payment method mentioned in Payment.paymentMethod.
Note: For orders that are subject to 'eBay Collect and Remit' tax, which includes US state-mandated sales tax, Federal and Provincial Sales Tax in Canada, 'Good and Services' tax in Canada, Australia, and New Zealand, and VAT collected for UK or EU, the 'Collect and Remit' tax amount for the order will be included in this amount.value field (and in the amount.convertedFromValue field if currency conversion is applicable).
To determine if 'Collect and Remit' taxes were added into this totalDueSeller value, the user can check for the corresponding lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is included in this amount:STATE_SALES_TAX: USPROVINCE_SALES_TAX: Provincial Sales Tax in CanadaGST: Canada, Australia, and New ZealandVAT: UK and EU countries
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "paymentDate": {
+ "type": "string",
+ "description": "The date and time that the payment was received by the seller. This field will not be returned if buyer has yet to pay for the order. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "paymentHolds": {
+ "type": "array",
+ "description": "This container is only returned if eBay is temporarily holding the seller's funds for the order. If a payment hold has been placed on the order, this container includes the reason for the payment hold, the expected release date of the funds into the seller's account, the current state of the hold, and as soon as the payment hold has been released, the actual release date.",
+ "items": {
+ "$ref": "#/components/schemas/PaymentHold"
+ }
+ },
+ "paymentMethod": {
+ "type": "string",
+ "description": "The payment method used to pay for the order. See the PaymentMethodTypeEnum type for more information on the payment methods. For implementation help, refer to eBay API documentation"
+ },
+ "paymentReferenceId": {
+ "type": "string",
+ "description": "This field is only returned if payment has been made by the buyer, and the paymentMethod is ESCROW. This field contains a special ID for ESCROW."
+ },
+ "paymentStatus": {
+ "type": "string",
+ "description": "The enumeration value returned in this field indicates the status of the payment for the order. See the PaymentStatusEnum type definition for more information on the possible payment states. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used to provide details about the seller payments for an order."
+ },
+ "PaymentDispute": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "This container shows the dollar value associated with the payment dispute in the currency used by the seller's marketplace.",
+ "$ref": "#/components/schemas/SimpleAmount"
+ },
+ "availableChoices": {
+ "type": "array",
+ "description": "The value(s) returned in this array indicate the choices that the seller has when responding to the payment dispute. Once the seller has responded to the payment dispute, this field will no longer be shown, and instead, the sellerResponse field will show the decision that the seller made.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "buyerProvided": {
+ "description": "This container is returned if the buyer is returning one or more line items in an order that is associated with the payment dispute, and that buyer has provided return shipping tracking information and/or a note about the return.",
+ "$ref": "#/components/schemas/InfoFromBuyer"
+ },
+ "buyerUsername": {
+ "type": "string",
+ "description": "This is the eBay user ID of the buyer that initiated the payment dispute."
+ },
+ "closedDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when the payment dispute was closed, so this field is only returned for payment disputes in the CLOSED state.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ },
+ "evidence": {
+ "type": "array",
+ "description": "This container shows any evidence that has been provided by the seller to contest the payment dispute. Evidence may include shipment tracking information, proof of authentication documentation, image(s) to proof that an item is as described, or financial documentation/invoice.
This container is only returned if the seller has provided at least one document used as evidence against the payment dispute.",
+ "items": {
+ "$ref": "#/components/schemas/DisputeEvidence"
+ }
+ },
+ "evidenceRequests": {
+ "type": "array",
+ "description": "This container is returned if one or more evidence documents are being requested from the seller.",
+ "items": {
+ "$ref": "#/components/schemas/EvidenceRequest"
+ }
+ },
+ "lineItems": {
+ "type": "array",
+ "description": "This array is used to identify one or more order line items associated with the payment dispute. There will always be at least one itemId/lineItemId pair returned in this array.",
+ "items": {
+ "$ref": "#/components/schemas/OrderLineItems"
+ }
+ },
+ "monetaryTransactions": {
+ "type": "array",
+ "description": "This array provide details about one or more monetary transactions that occur as part of a payment dispute. This array is only returned once one or more monetary transacations occur with a payment dispute.",
+ "items": {
+ "$ref": "#/components/schemas/MonetaryTransaction"
+ }
+ },
+ "note": {
+ "type": "string",
+ "description": "This field shows information that the seller provides about the dispute, such as the basis for the dispute, any relevant evidence, tracking numbers, and so forth.
This field is limited to 1000 characters."
+ },
+ "openDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when the payment dispute was opened. This field is returned for payment disputes in all states.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ },
+ "orderId": {
+ "type": "string",
+ "description": "This is the unique identifier of the order involved in the payment dispute."
+ },
+ "paymentDisputeId": {
+ "type": "string",
+ "description": "This is the unique identifier of the payment dispute. This is the same identifier that is passed in to the call URI. This identifier is automatically created by eBay once the payment dispute comes into the eBay system."
+ },
+ "paymentDisputeStatus": {
+ "type": "string",
+ "description": "The enumeration value in this field gives the current status of the payment dispute. The status of a payment dispute partially determines other fields that are returned in the response. For implementation help, refer to eBay API documentation"
+ },
+ "reason": {
+ "type": "string",
+ "description": "The enumeration value in this field gives the reason why the buyer initiated the payment dispute. See DisputeReasonEnum type for a description of the supported reasons that buyers can give for initiating a payment dispute. For implementation help, refer to eBay API documentation"
+ },
+ "resolution": {
+ "description": "This container gives details about a payment dispute that has been resolved. This container is only returned for resolved/closed payment disputes.",
+ "$ref": "#/components/schemas/PaymentDisputeOutcomeDetail"
+ },
+ "respondByDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when the seller must response to a payment dispute, so this field is only returned for payment disputes in the ACTION_NEEDED state. For payment disputes that currently require action by the seller, that same seller should look at the availableChoices array to see the available actions.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ },
+ "returnAddress": {
+ "description": "This container gives the address where the order will be returned to. This container is returned if the seller is accepting the payment dispute and will issue a refund to the buyer once the item is returned to this address.",
+ "$ref": "#/components/schemas/ReturnAddress"
+ },
+ "revision": {
+ "type": "integer",
+ "description": "This integer value indicates the revision number of the payment dispute. Each time an action is taken against a payment dispute, this integer value increases by 1.",
+ "format": "int32"
+ },
+ "sellerResponse": {
+ "type": "string",
+ "description": "The enumeration value returned in this field indicates how the seller has responded to the payment dispute. The seller has the option of accepting the payment dispute and agreeing to issue a refund, accepting the payment dispute and agreeing to issue a refund as long as the buyer returns the item, or contesting the payment dispute. This field is returned as soon as the seller makes an initial decision on the payment dispute. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used by the base response of the getPaymentDispute method. The getPaymentDispute method retrieves detailed information on a specific payment dispute."
+ },
+ "PaymentDisputeActivity": {
+ "type": "object",
+ "properties": {
+ "activityDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time of the payment dispute activity.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ },
+ "activityType": {
+ "type": "string",
+ "description": "This enumeration value indicates the type of activity that occured on the payment dispute. For example, a value of DISPUTE_OPENED is returned when a payment disute is first created, a value indicating the seller's decision on the dispute, such as SELLER_CONTEST, is returned when seller makes a decision to accept or contest dispute, and a value of DISPUTE_CLOSED is returned when a payment disute is resolved. See ActivityEnum for an explanation of each of the values that may be returned here. For implementation help, refer to eBay API documentation"
+ },
+ "actor": {
+ "type": "string",
+ "description": "This enumeration value indicates the actor that performed the action. Possible values include the BUYER, SELLER, CS_AGENT (eBay customer service), or SYSTEM. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used by each recorded activity on a payment dispute, from creation to resolution."
+ },
+ "PaymentDisputeActivityHistory": {
+ "type": "object",
+ "properties": {
+ "activity": {
+ "type": "array",
+ "description": "This array holds all activities of a payment dispute, from creation to resolution. For each activity, the activity type, the actor, and a timestamp is shown. The getActivities response is dynamic, and grows with each recorded activity.",
+ "items": {
+ "$ref": "#/components/schemas/PaymentDisputeActivity"
+ }
+ }
+ },
+ "description": "This type is used by the base response of the getActivities method, and includes a log of all activities of a payment dispute, from creation to resolution."
+ },
+ "PaymentDisputeOutcomeDetail": {
+ "type": "object",
+ "properties": {
+ "fees": {
+ "description": "This container will show the dollar value of any fees associated with the payment dispute. This container is only returned if there are fees associated with the payment dispute.",
+ "$ref": "#/components/schemas/SimpleAmount"
+ },
+ "protectedAmount": {
+ "description": "This container shows the amount of money that the seller is protected against in a payment dispute under eBay's seller protection policy.",
+ "$ref": "#/components/schemas/SimpleAmount"
+ },
+ "protectionStatus": {
+ "type": "string",
+ "description": "This enumeration value indicates if the seller is fully protected, partially protected, or not protected by eBay for the payment dispute. This field is always returned once the payment dispute is resolved. For implementation help, refer to eBay API documentation"
+ },
+ "reasonForClosure": {
+ "type": "string",
+ "description": "The enumeration value returned in this field indicates the outcome of the payment dispute for the seller. This field is always returned once the payment dispute is resolved. For implementation help, refer to eBay API documentation"
+ },
+ "recoupAmount": {
+ "description": "This container shows the dollar amount being recouped from the seller. This container is empty if the seller wins the payment dispute or if the seller is fully protected by eBay's seller protection policy.",
+ "$ref": "#/components/schemas/SimpleAmount"
+ },
+ "totalFeeCredit": {
+ "description": "This container shows the amount of money in selling fee credits due back to the seller after a payment dispute is settled.",
+ "$ref": "#/components/schemas/SimpleAmount"
+ }
+ },
+ "description": "This type is used by the resolution container that is returned for payment disputes that have been resolved."
+ },
+ "PaymentDisputeSummary": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "This container shows the dollar value associated with the payment dispute in the currency used by the seller's marketplace. This container is returned for all payment disputes returned in the response.",
+ "$ref": "#/components/schemas/SimpleAmount"
+ },
+ "buyerUsername": {
+ "type": "string",
+ "description": "This is the buyer's eBay user ID. This field is returned for all payment disputes returned in the response."
+ },
+ "closedDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when the payment dispute was closed, so this field is only returned for payment disputes in the CLOSED state.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ },
+ "openDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when the payment dispute was opened. This field is returned for payment disputes in all states.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ },
+ "orderId": {
+ "type": "string",
+ "description": "This is the unique identifier of the order involved in the payment dispute."
+ },
+ "paymentDisputeId": {
+ "type": "string",
+ "description": "This is the unique identifier of the payment dispute. This identifier is automatically created by eBay once the payment dispute comes into the eBay system. This identifier is passed in at the end of the getPaymentDispute call URI to retrieve a specific payment dispute. The getPaymentDispute method returns more details about a payment dispute than the getPaymentDisputeSummaries method."
+ },
+ "paymentDisputeStatus": {
+ "type": "string",
+ "description": "The enumeration value in this field gives the current status of the payment dispute. For implementation help, refer to eBay API documentation"
+ },
+ "reason": {
+ "type": "string",
+ "description": "The enumeration value in this field gives the reason why the buyer initiated the payment dispute. See DisputeReasonEnum type for a description of the supported reasons that buyers can give for initiating a payment dispute. For implementation help, refer to eBay API documentation"
+ },
+ "respondByDate": {
+ "type": "string",
+ "description": "The timestamp in this field shows the date/time when the seller must response to a payment dispute, so this field is only returned for payment disputes in the ACTION_NEEDED state. For payment disputes that require action by the seller, that same seller must call getPaymentDispute to see the next action(s) that they can take against the payment dispute.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
+ }
+ },
+ "description": "This type is used by each payment dispute that is returned with the getPaymentDisputeSummaries method."
+ },
+ "PaymentHold": {
+ "type": "object",
+ "properties": {
+ "expectedReleaseDate": {
+ "type": "string",
+ "description": "The date and time that the payment being held is expected to be released to the seller. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field will be returned if known by eBay.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "holdAmount": {
+ "description": "The monetary amount of the payment being held. This field is always returned with the paymentHolds array. ",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "holdReason": {
+ "type": "string",
+ "description": "The reason that the payment is being held. A seller's payment may be held for a number of reasons, including when the seller is new, the seller's level is below standard, or if a return case or 'Significantly not as described' case is pending against the seller. This field is always returned with the paymentHolds array."
+ },
+ "holdState": {
+ "type": "string",
+ "description": "The current stage or condition of the hold. This field is always returned with the paymentHolds array.
Applicable values:HELDHELD_PENDINGNOT_HELDRELEASE_CONFIRMEDRELEASE_FAILEDRELEASE_PENDINGRELEASED
"
+ },
+ "releaseDate": {
+ "type": "string",
+ "description": "The date and time that the payment being held was actually released to the seller. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the seller's payment is actually released into the seller's account.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "sellerActionsToRelease": {
+ "type": "array",
+ "description": "A list of one or more possible actions that the seller can take to expedite the release of the payment hold.",
+ "items": {
+ "$ref": "#/components/schemas/SellerActionsToRelease"
+ }
+ }
+ },
+ "description": "This type contains information about a hold placed on a payment to a seller for an order, including the reason why the buyer's payment for the order is being held, the expected release date of the funds into the seller's account, the current state of the hold, and the actual release date if the payment has been released, and possible actions the seller can take to expedite the payout of funds into their account."
+ },
+ "PaymentSummary": {
+ "type": "object",
+ "properties": {
+ "payments": {
+ "type": "array",
+ "description": "This array consists of payment information for the order, including payment status, payment method, payment amount, and payment date. This array is always returned, although some of the fields under this container will not be returned until payment has been made.",
+ "items": {
+ "$ref": "#/components/schemas/Payment"
+ }
+ },
+ "refunds": {
+ "type": "array",
+ "description": "This array is always returned, but is returned as an empty array unless the seller has submitted a partial or full refund to the buyer for the order. If a refund has occurred, the refund amount and refund date will be shown for each refund.",
+ "items": {
+ "$ref": "#/components/schemas/OrderRefund"
+ }
+ },
+ "totalDueSeller": {
+ "description": "This is the total price that the seller receives for the entire order after all costs (item cost, delivery cost, taxes) are added for all line items, minus any discounts and/or promotions for any of the line items. Note that this value is subject to change before payment is actually made by the buyer (if the paymentStatus value was PENDING or FAILED), or if a partial or full refund occurs with the order.
Note: For orders that are subject to 'eBay Collect and Remit' tax, the 'Collect and Remit' tax amount for the order will be included in this totalDueSeller value.
To determine if 'Collect and Remit' taxes were added into this totalDueSeller value, the user can check for the corresponding lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is included in this amount:STATE_SALES_TAX: USPROVINCE_SALES_TAX: Provincial Sales Tax in CanadaGST: Canada, Australia, and New ZealandVAT: VAT collected for UK and EU countries
",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type contains information about the various monetary exchanges that apply to the net balance due for the order."
+ },
+ "Phone": {
+ "type": "object",
+ "properties": {
+ "countryCode": {
+ "type": "string",
+ "description": " The two-letter, ISO 3166 code associated with the seller's phone number. This field is needed if the buyer is located in a different country than the seller. It is also OK to provide if the buyer and seller are both located in the same country
See CountryCodeEnum for a list of supported values."
+ },
+ "number": {
+ "type": "string",
+ "description": "The seller's primary phone number associated with the return address. When this number is provided in a contestPaymentDispute or contestPaymentDispute method, it is provided as one continuous numeric string, including the area code. So, if the phone number's area code was '408', a number in this field may look something like this:
\"number\" : \"4088084356\"
If the buyer is located in a different country than the seller, the seller's country code will need to be specified in the countryCode field."
+ }
+ },
+ "description": "This type is used by the returnAddress
This field is always returned with the pickupStep container."
+ }
+ },
+ "description": "This type is used to indicate the merchant's store where the buyer will pickup their In-Store Pickup order. The pickupStep container is only returned for In-Store Pickup orders. The In-Store Pickup feature is supported in the US, Canada, UK, Germany, and Australia marketplaces."
+ },
+ "PostSaleAuthenticationProgram": {
+ "type": "object",
+ "properties": {
+ "outcomeReason": {
+ "type": "string",
+ "description": "This field indicates the result of the authenticity verification inspection on an order line item. This field is not returned when the status value of the order line item is PENDING or PASSED. The possible values returned here are NOT_AUTHENTIC, NOT_AS_DESCRIBED, CUSTOMIZED, MISCATEGORIZED, or NOT_AUTHENTIC_NO_RETURN. For implementation help, refer to eBay API documentation"
+ },
+ "status": {
+ "type": "string",
+ "description": "The value in this field indicates whether the order line item has passed or failed the authenticity verification inspection, or if the inspection and/or results are still pending. The possible values returned here are PENDING, PASSED, FAILED, or PASSED_WITH_EXCEPTION. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used to provide the status and outcome of an order line item going through the Authenticity Guarantee verification process."
+ },
+ "PricingSummary": {
+ "type": "object",
+ "properties": {
+ "adjustment": {
+ "description": "This container shows the total amount of any adjustments that were applied to the cost of the item(s) in the order. This amount does not include shipping, discounts, fixed fees, or taxes.
This container is only returned if price adjustments were made to the order after the initial transaction/commitment to buy occurred.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "deliveryCost": {
+ "description": "This container shows the total cost of delivering the order to the buyer, before any shipping/delivery discount is applied.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "deliveryDiscount": {
+ "description": "This container shows the total amount of delivery discounts (including shipping discounts) that apply to the order. This should be a negative real number.
This container is only returned if delivery discounts are being applied to the order.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "fee": {
+ "description": "This container shows the total amount of any special fees applied to the order, such as a tire recycling fee or an electronic waste fee.
This container is returned if special fees are being applied to the order and if the fieldGroups is set to TAX_BREAKDOWN.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "priceDiscount": {
+ "description": "This container shows the total amount of all item price discounts (including promotions) that apply to the order and reduce its cost to the buyer. This should be a negative real number.
This container is only returned if special discounts are being applied to the order.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "priceSubtotal": {
+ "description": "This container shows the cumulative costs of of all units of all line items in the order, before any discount is applied.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "tax": {
+ "description": "This container shows the total amount of tax for the order. To calculate the tax percentage rate, divide this value by the value of the total field.
This container is only returned if any type of tax (sales tax, tax on shipping, tax on handling, import tax, etc.) is applied to the order.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "total": {
+ "description": "The total cost of the order after adding all line item costs, delivery costs, sales tax, and special fees, and then subtracting all special discounts and price adjustments.
Note: For orders that are subject to 'eBay Collect and Remit' tax, the 'Collect and Remit' tax amount for the order will be included in this total value only when the fieldGroups query parameter is set to TAX_BREAKDOWN. If the fieldGroups query parameter is not set to TAX_BREAKDOWN, 'Collect and Remit' will not be added into this total value.
To determine if 'Collect and Remit' taxes were added into this total value, the user can check for the corresponding lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is included in this amount:STATE_SALES_TAX: US state-mandated sales taxPROVINCE_SALES_TAX: Provincial Sales Tax in CanadaGST: 'Good and Services' tax in Canada, Australia, and New ZealandVAT: VAT collected for UK and EU countries
",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type contains a summary of cumulative costs and charges for all line items of an order, including item price, price adjustments, sales taxes, delivery costs, and order discounts."
+ },
+ "Program": {
+ "type": "object",
+ "properties": {
+ "authenticityVerification": {
+ "description": "This field is returned when the third-party authenticator performs the authentication verification inspection on the order line item. Different values will be returned based on whether the item passed or failed the authentication verification inspection.",
+ "$ref": "#/components/schemas/PostSaleAuthenticationProgram"
+ },
+ "ebayShipping": {
+ "description": "This container is returned only if the order is an eBay shipping order. It consists of a field that indicates the provider of a shipping label for this order.",
+ "$ref": "#/components/schemas/EbayShipping"
+ },
+ "ebayVault": {
+ "description": "This field provides information about the eBay vault program that has been selected for an order. This is returned only for those items that are eligible for the eBay Vault Program.",
+ "$ref": "#/components/schemas/EbayVaultProgram"
+ },
+ "ebayInternationalShipping": {
+ "description": "This container is returned if the order is being fulfilled through eBay International Shipping.",
+ "$ref": "#/components/schemas/EbayInternationalShipping"
+ },
+ "fulfillmentProgram": {
+ "description": "This field provides details about an order line item being handled by eBay fulfillment. It is only returned for paid orders being fulfilled by eBay or an eBay fulfillment partner.",
+ "$ref": "#/components/schemas/EbayFulfillmentProgram"
+ }
+ },
+ "description": "This type is returned for order line items eligible for the Authenticity Guarantee service and/or for order line items fulfilled by the eBay Fulfillment program or eBay shipping."
+ },
+ "Property": {
+ "type": "object",
+ "properties": {
+ "propertyDisplayName": {
+ "type": "string",
+ "description": "The display name of the motor vehicle aspect. This is the localized name of the compatibility property."
+ },
+ "propertyName": {
+ "type": "string",
+ "description": "The name of the motor vehicle aspect.
For example, typical vehicle property names are 'Make', 'Model', 'Year', 'Engine', and 'Trim', but will vary based on the eBay marketplace and the eBay category."
+ },
+ "propertyValue": {
+ "type": "string",
+ "description": "The value of the property specified in the propertyName field.
For example, if the propertyName is Make, then the propertyValue will be the specific make of the vehicle, such as Toyota."
+ }
+ },
+ "description": "This type defines the property name and value for an order."
+ },
+ "Refund": {
+ "type": "object",
+ "properties": {
+ "refundId": {
+ "type": "string",
+ "description": "The unique identifier of the order refund. This value is returned unless the refund operation fails (refundStatus value shows FAILED). This identifier can be used to track the status of the refund through a getOrder or getOrders call. For order-level refunds, check the paymentSummary.refunds.refundId field in the getOrder/getOrders response, and for line item level refunds, check the lineItems.refunds.refundId field(s) in the getOrder/getOrders response."
+ },
+ "refundStatus": {
+ "type": "string",
+ "description": "The value returned in this field indicates the success or failure of the refund operation. A successful issueRefund operation should result in a value of PENDING. A failed issueRefund operation should result in a value of FAILED, and an HTTP status code and/or and API error code may also get returned to possibly indicate the issue.
The refunds issued through this method are processed asynchronously, so the refund will not show as 'Refunded' right away. A seller will have to make a subsequent getOrder call to check the status of the refund. The status of an order refund can be found in the paymentSummary.refunds.refundStatus field of the getOrder response. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This is the base type of the issueRefund response payload. As long as the issueRefund method does not trigger an error, a response payload will be returned."
+ },
+ "RefundItem": {
+ "type": "object",
+ "properties": {
+ "refundAmount": {
+ "description": "This container is used to specify the amount of the refund for the corresponding order line item. If a seller wants to issue a refund for an entire order, the seller would use the orderLevelRefundAmount container instead.",
+ "$ref": "#/components/schemas/SimpleAmount"
+ },
+ "lineItemId": {
+ "type": "string",
+ "description": "The unique identifier of an order line item. This identifier is created once a buyer purchases a 'Buy It Now' item or if an auction listing ends with a winning bidder.
Either this field or the legacyReference container is needed to identify an individual order line item that will receive a refund.
This value is returned using the getOrders method."
+ },
+ "legacyReference": {
+ "description": "This container is needed if the seller is issuing a refund for an individual order line item, and wishes to use an item ID/transaction ID pair to identify the order line item.
Either this container or the lineItemId field is needed to identify an individual order line item that will receive a refund.
Note: This container should only be used if a seller is using the GetOrders method of the Trading API.",
+ "$ref": "#/components/schemas/LegacyReference"
+ }
+ },
+ "description": "This type is used if the seller is issuing a refund for one or more individual order line items in a multiple line item order. Otherwise, the seller just uses the orderLevelRefundAmount container to specify the amount of the refund for the entire order."
+ },
+ "ReturnAddress": {
+ "type": "object",
+ "properties": {
+ "addressLine1": {
+ "type": "string",
+ "description": "The first line of the street address."
+ },
+ "addressLine2": {
+ "type": "string",
+ "description": "The second line of the street address. This line is not always necessarily, but is often used for apartment number or suite number, or other relevant information that can not fit on the first line."
+ },
+ "city": {
+ "type": "string",
+ "description": "The city of the return address."
+ },
+ "country": {
+ "type": "string",
+ "description": "The country's two-letter, ISO 3166-1 country code. See the enumeration type for a country's value. For implementation help, refer to eBay API documentation"
+ },
+ "county": {
+ "type": "string",
+ "description": "The county of the return address. Counties are not applicable to all countries."
+ },
+ "fullName": {
+ "type": "string",
+ "description": "The full name of return address owner."
+ },
+ "postalCode": {
+ "type": "string",
+ "description": "The postal code of the return address."
+ },
+ "primaryPhone": {
+ "description": "This container shows the seller's primary phone number associated with the return address.",
+ "$ref": "#/components/schemas/Phone"
+ },
+ "stateOrProvince": {
+ "type": "string",
+ "description": "The state or province of the return address."
+ }
+ },
+ "description": "This type is used by the payment dispute methods, and is relevant if the buyer will be returning the item to the seller."
+ },
+ "SellerActionsToRelease": {
+ "type": "object",
+ "properties": {
+ "sellerActionToRelease": {
+ "type": "string",
+ "description": "A possible action that the seller can take to expedite the release of a payment hold. A sellerActionToRelease field is returned for each possible action that a seller may take. Possible actions may include providing shipping/tracking information, issuing a refund, providing refund information, contacting customer support, etc."
+ }
+ },
+ "description": "This type is used to state possible action(s) that a seller can take to release a payment hold placed against an order."
+ },
+ "ShippingFulfillment": {
+ "type": "object",
+ "properties": {
+ "fulfillmentId": {
+ "type": "string",
+ "description": "The unique identifier of the fulfillment; for example, 9405509699937003457459. This eBay-generated value is created with a successful createShippingFulfillment call."
+ },
+ "lineItems": {
+ "type": "array",
+ "description": "This array contains a list of one or more line items (and purchased quantity) to which the fulfillment applies.",
+ "items": {
+ "$ref": "#/components/schemas/LineItemReference"
+ }
+ },
+ "shipmentTrackingNumber": {
+ "type": "string",
+ "description": "The tracking number provided by the shipping carrier for the package shipped in this fulfillment. This field is returned if available."
+ },
+ "shippedDate": {
+ "type": "string",
+ "description": "The date and time that the fulfillment package was shipped. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field should only be returned if the package has been shipped.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
+ },
+ "shippingCarrierCode": {
+ "type": "string",
+ "description": "The eBay code identifying the shipping carrier for this fulfillment. This field is returned if available.
Note: The Trading API's ShippingCarrierCodeType enumeration type contains the most current list of eBay shipping carrier codes and the countries served by each carrier. See ShippingCarrierCodeType."
+ }
+ },
+ "description": "This type contains the complete details of an existing fulfillment for an order."
+ },
+ "ShippingFulfillmentDetails": {
+ "type": "object",
+ "properties": {
+ "lineItems": {
+ "type": "array",
+ "description": "This array contains a list of or more line items and the quantity that will be shipped in the same package.",
+ "items": {
+ "$ref": "#/components/schemas/LineItemReference"
+ }
+ },
+ "shippedDate": {
+ "type": "string",
+ "description": "This is the actual date and time that the fulfillment package was shipped. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. The seller should use the actual date/time that the package was shipped, but if this field is omitted, it will default to the current date/time.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z
Default: The current date and time."
+ },
+ "shippingCarrierCode": {
+ "type": "string",
+ "description": "The unique identifier of the shipping carrier being used to ship the line item(s). Technically, the shippingCarrierCode and trackingNumber fields are optional, but generally these fields will be provided if the shipping carrier and tracking number are known.
Note: Use the Trading API's GeteBayDetails call to retrieve the latest shipping carrier enumeration values. When making the GeteBayDetails call, include the DetailName field in the request payload and set its value to ShippingCarrierDetails. Each valid shipping carrier enumeration value is returned in a ShippingCarrierDetails.ShippingCarrier field in the response payload."
+ },
+ "trackingNumber": {
+ "type": "string",
+ "description": "The tracking number provided by the shipping carrier for this fulfillment. The seller should be careful that this tracking number is accurate since the buyer will use this tracking number to track shipment, and eBay has no way to verify the accuracy of this number.
This field and the shippingCarrierCode field are mutually dependent. If you include one, you must also include the other.
Note: If you include trackingNumber (and shippingCarrierCode) in the request, the resulting fulfillment's ID (returned in the HTTP location response header) is the tracking number. If you do not include shipment tracking information, the resulting fulfillment ID will default to an arbitrary number such as 999.
Note: Only alphanumeric characters are supported for shipment tracking numbers. Spaces, hyphens, and all other special characters are not supported. Do not include a space in the tracking number even if a space appears in the tracking number on the shipping label."
+ }
+ },
+ "description": "This type contains the details for creating a fulfillment for an order."
+ },
+ "ShippingFulfillmentPagedCollection": {
+ "type": "object",
+ "properties": {
+ "fulfillments": {
+ "type": "array",
+ "description": "This array contains one or more fulfillments required for the order that was specified in method endpoint.",
+ "items": {
+ "$ref": "#/components/schemas/ShippingFulfillment"
+ }
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of fulfillments in the specified order.
Note: If no fulfillments are found for the order, this field is returned with a value of 0.",
+ "format": "int32"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "This array is only returned if one or more errors or warnings occur with the call request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type contains the specifications for the entire collection of shipping fulfillments that are associated with the order specified by a getShippingFulfillments call. The fulfillments container returns an array of all the fulfillments in the collection."
+ },
+ "ShippingStep": {
+ "type": "object",
+ "properties": {
+ "shippingCarrierCode": {
+ "type": "string",
+ "description": "The unique identifier of the shipping carrier being used to ship the line item.
Note: The Trading API's GeteBayDetails call can be used to retrieve the latest shipping carrier and shipping service option enumeration values."
+ },
+ "shippingServiceCode": {
+ "type": "string",
+ "description": "The unique identifier of the shipping service option being used to ship the line item.
Note: Use the Trading API's GeteBayDetails call to retrieve the latest shipping carrier and shipping service option enumeration values. When making the GeteBayDetails call, include the DetailName field in the request payload and set its value to ShippingServiceDetails. Each valid shipping service option (returned in ShippingServiceDetails.ShippingService field) and corresponding shipping carrier (returned in ShippingServiceDetails.ShippingCarrier field) is returned in response payload."
+ },
+ "shipTo": {
+ "description": "This container consists of shipping and contact information about the individual or organization to whom the fulfillment package will be shipped.
Note: When FulfillmentInstructionsType is FULFILLED_BY_EBAY, there will be no shipTo address displayed.
Note: For Digitally Delivered Goods (DDG), this address is the same as the Buyer's Registration Address.
Note: For a Global Shipping Program shipment, this is the address of the international shipping provider's domestic warehouse. The international shipping provider is responsible for delivery to the final destination address. For more information, see Addressing Shipments.",
+ "$ref": "#/components/schemas/ExtendedContact"
+ },
+ "shipToReferenceId": {
+ "type": "string",
+ "description": "This is the unique identifer of the Global Shipping Program (GSP) shipment. This field is only returned if the line item is being shipped via GSP (the value of the fulfillmentStartInstructions.ebaySupportedFulfillment field will be true. The international shipping provider uses the shipToReferenceId value as the primary reference number to retrieve the relevant details about the buyer, the order, and the fulfillment, so the shipment can be completed.
Sellers must include this value on the shipping label immediately above the street address of the international shipping provider.
Example: \"Reference #1234567890123456\"
Note: This value is the same as the ShipToAddress.ReferenceID value returned by the Trading API's GetOrders call."
+ }
+ },
+ "description": "This type contains shipping information for a fulfillment, including the shipping carrier, the shipping service option, the shipment destination, and the Global Shipping Program reference ID."
+ },
+ "SimpleAmount": {
+ "type": "object",
+ "properties": {
+ "currency": {
+ "type": "string",
+ "description": "A three-letter ISO 4217 code (such as USD for US site) that indicates the currency of the amount in the value field. Both the value and currency fields are always returned with the amount container. For implementation help, refer to eBay API documentation"
+ },
+ "value": {
+ "type": "string",
+ "description": "The monetary amount of the payment dispute. Both the value and currency fields are always returned with the amount container."
+ }
+ },
+ "description": "This type defines the monetary value of the payment dispute, and the currency used."
+ },
+ "Tax": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "The monetary amount of the tax. The taxes array is always returned for each line item in the order, but this amount will only be returned when the line item is subject to any type of sales tax. ",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "taxType": {
+ "type": "string",
+ "description": "Tax type. This field is only available when fieldGroups is set to TAX_BREAKDOWN. If the order has fees, a breakdown of the fees is also provided. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type contains information about any sales tax applied to a line item."
+ },
+ "TaxAddress": {
+ "type": "object",
+ "properties": {
+ "city": {
+ "type": "string",
+ "description": "The city name that can be used by sellers for tax purpose."
+ },
+ "countryCode": {
+ "type": "string",
+ "description": "The country code that can be used by sellers for tax purpose, represented as a two-letter ISO 3166-1 alpha-2 country code. For example, US represents the United States, and DE represents Germany. For implementation help, refer to eBay API documentation"
+ },
+ "postalCode": {
+ "type": "string",
+ "description": "The postal code that can be used by sellers for tax purpose. Usually referred to as Zip codes in the US."
+ },
+ "stateOrProvince": {
+ "type": "string",
+ "description": "The state name that can be used by sellers for tax purpose."
+ }
+ },
+ "description": "This container consists of address information that can be used by sellers for tax purpose."
+ },
+ "TaxIdentifier": {
+ "type": "object",
+ "properties": {
+ "taxpayerId": {
+ "type": "string",
+ "description": "This value is the unique tax ID associated with the buyer. The type of tax identification is shown in the taxIdentifierType field."
+ },
+ "taxIdentifierType": {
+ "type": "string",
+ "description": "This enumeration value indicates the type of tax identification being used for the buyer. The different tax types are defined in the TaxIdentifierTypeEnum type. For implementation help, refer to eBay API documentation"
+ },
+ "issuingCountry": {
+ "type": "string",
+ "description": "This two-letter code indicates the country that issued the buyer's tax ID. The country that the two-letter code represents can be found in the CountryCodeEnum type, or in the ISO 3166 standard. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used by the taxIdentifier container that is returned in getOrder. The taxIdentifier container consists of taxpayer identification information for buyers from Italy, Spain, or Guatemala. It is currently only returned for orders occurring on the eBay Italy or eBay Spain marketplaces.
Note: Currently, the taxIdentifier container is only returned in getOrder and not in getOrders. So, if a seller wanted to view a buyer's tax information for a particular order returned in getOrders, that seller would need to use the orderId value for that particular order, and then run a getOrder call against that order ID. "
+ },
+ "TrackingInfo": {
+ "type": "object",
+ "properties": {
+ "shipmentTrackingNumber": {
+ "type": "string",
+ "description": "This string value represents the shipment tracking number of the package."
+ },
+ "shippingCarrierCode": {
+ "type": "string",
+ "description": "This string value represents the shipping carrier used to ship the package."
+ }
+ },
+ "description": "This type is used for seller provided shipment tracking information."
+ },
+ "UpdateEvidencePaymentDisputeRequest": {
+ "type": "object",
+ "properties": {
+ "evidenceId": {
+ "type": "string",
+ "description": "The unique identifier of the evidence set that is being updated with new evidence files.
This ID is returned under the evidence array in the getPaymentDispute response."
+ },
+ "evidenceType": {
+ "type": "string",
+ "description": "This field is used to indicate the type of evidence being provided through one or more evidence files. All evidence files (if more than one) should be associated with the evidence type passed in this field.
See the EvidenceTypeEnum type for the supported evidence types. For implementation help, refer to eBay API documentation"
+ },
+ "files": {
+ "type": "array",
+ "description": "This array is used to specify one or more evidence files that will be added to the evidence set associated with a payment dispute. At least one evidence file must be specified in the files array.
The unique identifier of an evidence file is returned in the response payload of the uploadEvidence method.",
+ "items": {
+ "$ref": "#/components/schemas/FileEvidence"
+ }
+ },
+ "lineItems": {
+ "type": "array",
+ "description": "This required array identifies the order line item(s) for which the evidence file(s) will be applicable.
These values are returned under the evidenceRequests.lineItems array in the getPaymentDispute response.
Note: Both the itemId and lineItemID fields are needed to identify each order line item.",
+ "items": {
+ "$ref": "#/components/schemas/OrderLineItems"
+ }
+ }
+ },
+ "description": "This type is used by the request payload of the updateEvidence method. The updateEvidence method is used to update an existing evidence set against a payment dispute with one or more evidence files."
+ }
+ },
+ "securitySchemes": {
+ "api_auth": {
+ "type": "oauth2",
+ "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
+ "flows": {
+ "authorizationCode": {
+ "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
+ "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
+ "scopes": {
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment": "View and manage your order fulfillments",
+ "https://api.ebay.com/oauth/api_scope/sell.finances": "View and manage your payment and order information to display this information to you and allow you to initiate refunds using the third party application",
+ "https://api.ebay.com/oauth/api_scope/sell.payment.dispute": "View and manage disputes and related details (including payment and order information).",
+ "https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly": "View your order fulfillments"
+ }
+ }
}
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.payment.dispute"
- ]
- }
- ]
- },
- "servers": [
- {
- "url": "https://apiz.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/fulfillment/v1"
- }
- }
- }
- ]
- }
- },
- "components": {
- "schemas": {
- "AcceptPaymentDisputeRequest": {
- "type": "object",
- "properties": {
- "returnAddress": {
- "description": "This container is used if the seller wishes to provide a return address to the buyer. This container should be used if the seller is requesting that the buyer return the item.",
- "$ref": "#/components/schemas/ReturnAddress"
- },
- "revision": {
- "type": "integer",
- "description": "This integer value indicates the revision number of the payment dispute. This field is required. The current revision number for a payment dispute can be retrieved with the getPaymentDispute method. Each time an action is taken against a payment dispute, this integer value increases by 1.",
- "format": "int32"
- }
- },
- "description": "This type is used by base request of the acceptPaymentDispute method."
- },
- "AddEvidencePaymentDisputeRequest": {
- "type": "object",
- "properties": {
- "evidenceType": {
- "type": "string",
- "description": "This field is used to indicate the type of evidence being provided through one or more evidence files. All evidence files (if more than one) should be associated with the evidence type passed in this field.
See the EvidenceTypeEnum type for the supported evidence types. For implementation help, refer to eBay API documentation"
- },
- "files": {
- "type": "array",
- "description": "This array is used to specify one or more evidence files that will become part of a new evidence set associated with a payment dispute. At least one evidence file must be specified in the files array.",
- "items": {
- "$ref": "#/components/schemas/FileEvidence"
- }
- },
- "lineItems": {
- "type": "array",
- "description": "This array identifies the order line item(s) for which the evidence file(s) will be applicable.
These values are returned under the evidenceRequests.lineItems array in the getPaymentDispute response.",
- "items": {
- "$ref": "#/components/schemas/OrderLineItems"
- }
- }
- },
- "description": "This type is used by the request payload of the addEvidence method. The addEvidence method is used to create a new evidence set against a payment dispute with one or more evidence files."
- },
- "AddEvidencePaymentDisputeResponse": {
- "type": "object",
- "properties": {
- "evidenceId": {
- "type": "string",
- "description": "The value returned in this field is the unique identifier of the newly-created evidence set. Upon a successful call, this value is automatically genererated. This new evidence set for the payment dispute includes the evidence file(s) that were passed in to the fileId array in the request payload. The evidenceId value will be needed if the seller wishes to add to the evidence set by using the updateEvidence method, or if they want to retrieve a specific evidence file within the evidence set by using the fetchEvidenceContent method."
- }
- },
- "description": "This type is used by the response payload of the addEvidence method. Its only field is an unique identifier of an evidence set."
- },
- "Address": {
- "type": "object",
- "properties": {
- "addressLine1": {
- "type": "string",
- "description": "The first line of the street address.
Note: addressLine1 will not be returned for any order that is more than 90 days old."
- },
- "addressLine2": {
- "type": "string",
- "description": "The second line of the street address. This field can be used for additional address information, such as a suite or apartment number. This field will be returned if defined for the shipping address.
Note: addressLine2 will not be returned for any order that is more than 90 days old."
- },
- "city": {
- "type": "string",
- "description": "The city of the shipping destination."
- },
- "countryCode": {
- "type": "string",
- "description": "The country of the shipping destination, represented as a two-letter ISO 3166-1 alpha-2 country code. For example, US represents the United States, and DE represents Germany. For implementation help, refer to eBay API documentation"
- },
- "county": {
- "type": "string",
- "description": "The county of the shipping destination. Counties typically, but not always, contain multiple cities or towns. This field is returned if known/available."
- },
- "postalCode": {
- "type": "string",
- "description": "The postal code of the shipping destination. Usually referred to as Zip codes in the US. Most countries have postal codes, but not all. The postal code will be returned if applicable."
- },
- "stateOrProvince": {
- "type": "string",
- "description": "The state or province of the shipping destination. Most countries have states or provinces, but not all. The state or province will be returned if applicable."
- }
- },
- "description": "This type contains the details of a geographical address."
- },
- "Amount": {
- "type": "object",
- "properties": {
- "convertedFromCurrency": {
- "type": "string",
- "description": "A three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency. For implementation help, refer to eBay API documentation"
- },
- "convertedFromValue": {
- "type": "string",
- "description": "The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field."
- },
- "currency": {
- "type": "string",
- "description": "A three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.
Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation"
- },
- "value": {
- "type": "string",
- "description": "The monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.
Required in the amount type."
- }
- },
- "description": "This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable."
- },
- "AppliedPromotion": {
- "type": "object",
- "properties": {
- "description": {
- "type": "string",
- "description": "A description of the applied sales promotion."
- },
- "discountAmount": {
- "description": "The monetary amount of the sales promotion.",
- "$ref": "#/components/schemas/Amount"
- },
- "promotionId": {
- "type": "string",
- "description": "An eBay-generated unique identifier of the sales promotion.
Multiple types of sales promotions are available to eBay Store owners, including order size/volume discounts, shipping discounts, special coupons, and price markdowns. Sales promotions can be managed through the Marketing tab of Seller Hub in My eBay, or by using the Trading API's SetPromotionalSale call or the Marketing API's createItemPromotion method."
- }
- },
- "description": "This type contains information about a sales promotion that is applied to a line item."
- },
- "AppointmentDetails": {
- "type": "object",
- "properties": {
- "appointmentEndTime": {
- "type": "string",
- "description": "The date and time the appointment ends, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Required for tire installation.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2022-10-28T00:00:00.000Z"
- },
- "appointmentStartTime": {
- "type": "string",
- "description": "The date and time the appointment begins, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2022-10-28T00:10:00.000Z"
- },
- "appointmentStatus": {
- "type": "string",
- "description": "The status of the appointment. For implementation help, refer to eBay API documentation"
- },
- "appointmentType": {
- "type": "string",
- "description": "The type of appointment. MACRO appointments only have a start time (not bounded with end time). TIME_SLOT appointments have a period (both start time and end time). Required for tire installation. For implementation help, refer to eBay API documentation"
- },
- "appointmentWindow": {
- "type": "string",
- "description": "Appointment window for MACRO appointments. For implementation help, refer to eBay API documentation"
- },
- "serviceProviderAppointmentDate": {
- "type": "string",
- "description": "Service provider date of the appointment (no time stamp). Returned only for MACRO appointment types."
- }
- },
- "description": "This type contains information used by the installation provider concerning appointment details selected by the buyer"
- },
- "Buyer": {
- "type": "object",
- "properties": {
- "buyerRegistrationAddress": {
- "description": "Buyer's contact information that includes the buyer's name, email, phone number, and address.",
- "$ref": "#/components/schemas/ExtendedContact"
- },
- "taxAddress": {
- "description": "This container consists of address information that can be used by sellers for tax purpose.
Note: When using the eBay vault program, if an item is shipped to a vault, the tax address will be the vault address.",
- "$ref": "#/components/schemas/TaxAddress"
- },
- "taxIdentifier": {
- "description": "This container consists of taxpayer identification information for buyers from Italy, Spain, or Guatemala. It is currently only returned for orders occurring on the eBay Italy or eBay Spain marketplaces.
Note: Currently, the taxIdentifier container is only returned in getOrder and not in getOrders. So, if a seller wanted to view a buyer's tax information for a particular order returned in getOrders, that seller would need to use the orderId value for that particular order, and then run a getOrder call against that order ID. ",
- "$ref": "#/components/schemas/TaxIdentifier"
- },
- "username": {
- "type": "string",
- "description": "The buyer's eBay user ID."
- }
- },
- "description": "This type contains information about the order's buyer."
- },
- "CancelRequest": {
- "type": "object",
- "properties": {
- "cancelCompletedDate": {
- "type": "string",
- "description": "The date and time that the order cancellation was completed, if applicable. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the cancellation request has actually been approved by the seller.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "cancelInitiator": {
- "type": "string",
- "description": "This string value indicates the party who made the initial cancellation request. Typically, either the 'Buyer' or 'Seller'. If a cancellation request has been made, this field should be returned."
- },
- "cancelReason": {
- "type": "string",
- "description": "The reason why the cancelInitiator initiated the cancellation request. Cancellation reasons for a buyer might include 'order placed by mistake' or 'order won't arrive in time'. For a seller, a typical cancellation reason is 'out of stock'. If a cancellation request has been made, this field should be returned."
- },
- "cancelRequestedDate": {
- "type": "string",
- "description": "The date and time that the order cancellation was requested. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is returned for each cancellation request.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "cancelRequestId": {
- "type": "string",
- "description": "The unique identifier of the order cancellation request. This field is returned for each cancellation request."
- },
- "cancelRequestState": {
- "type": "string",
- "description": "The current stage or condition of the cancellation request. This field is returned for each cancellation request. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type contains information about a buyer request to cancel an order."
- },
- "CancelStatus": {
- "type": "object",
- "properties": {
- "cancelledDate": {
- "type": "string",
- "description": "The date and time the order was cancelled, if applicable. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "cancelRequests": {
- "type": "array",
- "description": "This array contains details of one or more buyer requests to cancel the order.
For the getOrders call: This array is returned but is always empty.
For the getOrder call: This array is returned fully populated with information about any cancellation requests.",
- "items": {
- "$ref": "#/components/schemas/CancelRequest"
- }
- },
- "cancelState": {
- "type": "string",
- "description": "The state of the order with regard to cancellation. This field is always returned, and if there are no cancellation requests, a value of NONE_REQUESTED is returned. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type contains information about any requests that have been made to cancel an order."
- },
- "Charge": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "This container shows the amount and currency of the charge.",
- "$ref": "#/components/schemas/Amount"
- },
- "chargeType": {
- "type": "string",
- "description": "This field shows the type of buyer charge
Note: Currently, the only supported charge type is BUYER_PROTECTION. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used to display the charge type and the amount of the charge against the buyer."
- },
- "ContestPaymentDisputeRequest": {
- "type": "object",
- "properties": {
- "note": {
- "type": "string",
- "description": "This field shows information that the seller provides about the dispute, such as the basis for the dispute, any relevant evidence, tracking numbers, and so forth.
Max Length: 1000 characters."
- },
- "returnAddress": {
- "description": "This container is needed if the seller is requesting that the buyer return the item. If this container is used, all relevant fields must be included, including fullName and primaryPhone.
Note: If the Dispute Reason is SIGNIFICANTLY_NOT_AS_DESCRIBED, returnAddress is required.",
- "$ref": "#/components/schemas/ReturnAddress"
- },
- "revision": {
- "type": "integer",
- "description": "This integer value indicates the revision number of the payment dispute. This field is required. The current revision number for a payment dispute can be retrieved with the getPaymentDispute method. Each time an action is taken against a payment dispute, this integer value increases by 1.",
- "format": "int32"
- }
- },
- "description": "This type is used by the request payload of the contestPaymentDispute method."
- },
- "DeliveryCost": {
- "type": "object",
- "properties": {
- "discountAmount": {
- "description": "The amount of any shipping discount that has been applied to the line item. This container is returned only if a shipping discount applies to the line item.",
- "$ref": "#/components/schemas/Amount"
- },
- "handlingCost": {
- "description": "The amount of any handing cost that has been applied to the line item. This container is returned only if a handling cost applies to the line item.",
- "$ref": "#/components/schemas/Amount"
- },
- "importCharges": {
- "description": "The amount of any import charges applied to international shipping of the line item. This container is only returned if import charges apply to the line item.",
- "$ref": "#/components/schemas/Amount"
- },
- "shippingCost": {
- "description": "The total cost of shipping all units of the line item. This container is always returned even when the shipping cost is free, in which case the value field will show 0.0 (dollars).",
- "$ref": "#/components/schemas/Amount"
- },
- "shippingIntermediationFee": {
- "description": "This field shows the fee due to eBay's international shipping provider for a line item that is being shipped through the Global Shipping Program.
This container is only returned for line items being shipped internationally through the Global Shipping Program, which is currently only supported in the US and UK marketplaces.
Note: The value returned for this field will always be 0.0 for line items sold in the UK marketplace.",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type contains a breakdown of all costs associated with the fulfillment of a line item."
- },
- "DisputeAmount": {
- "type": "object",
- "properties": {
- "convertedFromCurrency": {
- "type": "string",
- "description": "The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency.
This field is only returned if/when currency conversion was applied by eBay. For implementation help, refer to eBay API documentation"
- },
- "convertedFromValue": {
- "type": "string",
- "description": "The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field.
This field is only returned if/when currency conversion was applied by eBay."
- },
- "currency": {
- "type": "string",
- "description": "A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type.
Default: The currency of the authenticated user's country. For implementation help, refer to eBay API documentation"
- },
- "exchangeRate": {
- "type": "string",
- "description": "The exchange rate used for the monetary conversion. This field shows the exchange rate used to convert the dollar value in the value field from the dollar value in the convertedFromValue field.
This field is only returned if/when currency conversion was applied by eBay."
- },
- "value": {
- "type": "string",
- "description": "The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type."
- }
- },
- "description": "This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable."
- },
- "DisputeEvidence": {
- "type": "object",
- "properties": {
- "evidenceId": {
- "type": "string",
- "description": "Unique identifier of the evidential file set. Potentially, each evidential file set can have more than one file, that is why there is this file set identifier, and then an identifier for each file within this file set."
- },
- "evidenceType": {
- "type": "string",
- "description": "This enumeration value shows the type of evidential file provided. For implementation help, refer to eBay API documentation"
- },
- "files": {
- "type": "array",
- "description": "This array shows the name, ID, file type, and upload date for each provided file.",
- "items": {
- "$ref": "#/components/schemas/FileInfo"
- }
- },
- "lineItems": {
- "type": "array",
- "description": "This array shows one or more order line items associated with the evidential document that has been provided.",
- "items": {
- "$ref": "#/components/schemas/OrderLineItems"
- }
- },
- "providedDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when the seller provided a requested evidential document to eBay.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- },
- "requestDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when eBay requested the evidential document from the seller in response to a payment dispute.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- },
- "respondByDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when the seller was expected to provide a requested evidential document to eBay.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- },
- "shipmentTracking": {
- "type": "array",
- "description": "This array shows the shipping carrier and shipment tracking number associated with each shipment package of the order. This array is returned under the evidence container if the seller has provided shipment tracking information as evidence to support PROOF_OF_DELIVERY for an INR-related payment dispute.",
- "items": {
- "$ref": "#/components/schemas/TrackingInfo"
- }
- }
- },
- "description": "This type is used by the evidence array that is returned in the getPaymentDispute response if one or more evidential documents are associated with the payment dispute. "
- },
- "DisputeSummaryResponse": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the getPaymentDisputeSummaries call request that produced the current page of the result set."
- },
- "limit": {
- "type": "integer",
- "description": "This value shows the maximum number of payment disputes that will appear on one page of the result set. The limit value can be passed in as a query parameter in the request, or if it is not used, it defaults to 200. If the value in the total field exceeds this limit value, there are multiple pages in the current result set.
Min: 1; Max: 200; Default: 200",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The getPaymentDisputeSummaries call URI to use if you wish to view the next page of the result set. For example, the following URI returns records 11 thru 20 from the collection of payment disputes:
path/payment_dispute_summary?limit=10&offset=10
This field is only returned if there is a next page of results to view based on the current input criteria."
- },
- "offset": {
- "type": "integer",
- "description": "This integer value indicates the number of payment disputes skipped before listing the first payment dispute from the result set. The offset value can be passed in as a query parameter in the request, or if it is not used, it defaults to 0 and the first payment dispute of the result set is shown at the top of the response.",
- "format": "int32"
- },
- "paymentDisputeSummaries": {
- "type": "array",
- "description": "Each payment dispute that matches the input criteria is returned under this array. If no payment disputes are found, an empty array is returned.",
- "items": {
- "$ref": "#/components/schemas/PaymentDisputeSummary"
- }
- },
- "prev": {
- "type": "string",
- "description": "The getPaymentDisputeSummaries call URI to use if you wish to view the previous page of the result set. For example, the following URI returns records 1 thru 10 from the collection of payment disputes:
path/payment_dispute_summary?limit=10&offset=0
This field is only returned if there is a previous page of results to view based on the current input criteria."
- },
- "total": {
- "type": "integer",
- "description": "This integer value is the total number of payment disputes that matched the input criteria. If the total number of entries exceeds the value that was set for limit in the request payload, you will have to make multiple API calls to see all pages of the results set. This field is returned even if it is 0.",
- "format": "int32"
- }
- },
- "description": "This type defines the base response payload of the getPaymentDisputeSummaries method. Each payment dispute that matches the input criteria is returned under the paymentDisputeSummaries array."
- },
- "EbayCollectAndRemitTax": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "The monetary amount of the 'Collect and Remit' tax. This currently includes:
- US state-mandated sales tax
- Federal and Provincial Sales Tax in Canada
- 'Goods and Services' tax in Canada, Australia, New Zealand, and Jersey
- VAT collected for the UK, EU countries, Kazakhstan, and Belarus
- Sales & Service Tax (SST) in Malaysia
Note: If the corresponding taxType is STATE_SALES_TAX, PROVINCE_SALES_TAX, GST, VAT, or SST and the lineItems.taxes container also appears for this line item with the same tax amount, the order is subject to 'eBay Collect and Remit' tax. For orders that are subject to 'eBay Collect and Remit' tax, the tax amount in this field will be included in the lineItems.total, paymentSummary.payments.amount, paymentSummary.totalDueSeller, and pricingSummary.total fields.",
- "$ref": "#/components/schemas/Amount"
- },
- "ebayReference": {
- "description": "This container field describes the line-item level VAT tax details.
",
- "$ref": "#/components/schemas/EbayTaxReference"
- },
- "taxType": {
- "type": "string",
- "description": "The type of tax and fees that eBay will collect and remit to the taxing or fee authority. See the TaxTypeEnum type definition for more information about each tax or fee type. For implementation help, refer to eBay API documentation"
- },
- "collectionMethod": {
- "type": "string",
- "description": "This field indicates the collection method used to collect the 'Collect and Remit' tax for the order. This field is always returned for orders subject to 'Collect and Remit' tax, and its value is always NET.
Note: Although the collectionMethod field is returned for all orders subject to 'Collect and Remit' tax, the collectionMethod field and the CollectionMethodEnum type are not currently of any practical use, although this field may have use in the future. If and when the logic of this field is changed, this note will be updated and a note will also be added to the Release Notes. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type contains information about the type and amount of tax that eBay will collect and remit to the state, province, country, or other taxing authority in the buyer's location, as required by that taxing authority.
'Collect and Remit' tax includes:- US state-mandated sales tax
- Federal and Provincial Sales Tax in Canada
- 'Goods and Services' tax in Canada, Australia, and New Zealand
- VAT collected for the UK and EU countries
"
- },
- "EbayCollectedCharges": {
- "type": "object",
- "properties": {
- "ebayShipping": {
- "description": "This container consists of costs related to eBay Shipping collected by eBay from the buyer of this order.",
- "$ref": "#/components/schemas/Amount"
- },
- "charges": {
- "type": "array",
- "description": "This array shows any charges that eBay collects from the buyer.
Note: Currently, the only supported charge type is BUYER_PROTECTION.",
- "items": {
- "$ref": "#/components/schemas/Charge"
- }
- }
- },
- "description": "This type contains the breakdown of costs that are collected by eBay from the buyer."
- },
- "EbayFulfillmentProgram": {
- "type": "object",
- "properties": {
- "fulfilledBy": {
- "type": "string",
- "description": "The value returned in this field indicates the party that is handling fulfillment of the order line item.
Valid value: EBAY"
- }
- },
- "description": "This type is used to provide details about an order line item being fulfilled by eBay or an eBay fulfillment partner."
- },
- "EbayInternationalShipping": {
- "type": "object",
- "properties": {
- "returnsManagedBy": {
- "type": "string",
- "description": "The value returned in this field indicates the party that is responsible for managing returns of the order line item.
Valid value: EBAY"
- }
- },
- "description": "This type is used to provide details about an order line item being managed through eBay International Shipping."
- },
- "EbayShipping": {
- "type": "object",
- "properties": {
- "shippingLabelProvidedBy": {
- "type": "string",
- "description": "This field contains the shipping label provider. If EBAY, this order is managed by eBay shipping and a free shipping label by eBay is downloadable by the seller via the eBay website."
- }
- },
- "description": "This type contains information about the management of the shipping for the order."
- },
- "EbayTaxReference": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "This field value is returned to indicate the VAT tax type, which will vary by country/region. This string value will be one of the following:ABN: if this string is returned, the ID in the value field is an Australia tax IDDDG: if this string is returned, it indicates that tax has been collected and remitted for Digitally Delivered Goods (DDG)IOSS: if this string is returned, the ID in the value field is an eBay EU or UK IOSS numberIRD: if this string is returned, the ID in the value field is an eBay New Zealand tax IDSST: if this string is returned, the ID in the value field is an eBay Malaysia taxNumberOSS: if this string is returned, the ID in the value field is an eBay Germany VAT IDVOEC: if this string is returned, the ID in the value field is an eBay Norway tax ID
"
- },
- "value": {
- "type": "string",
- "description": "The value returned in this field is the VAT identifier number (VATIN), which will vary by country/region. This field will be returned if VAT tax is applicable for the order. The name field indicates the VAT tax type, which will vary by country/region: - ABN: eBay AU tax ID
- IOSS: eBay EU IOSS number / eBay UK IOSS number
- IRD: eBay NZ tax ID
- OSS: eBay DE VAT ID
- SST: eBay MY taxNumber
- VOEC: eBay NO number
"
- }
- },
- "description": "This type describes the VAT tax details. The eBay VAT tax type and the eBay VAT identifier number will be returned if a VAT tax is applicable for the order.
"
- },
- "EbayVaultProgram": {
- "type": "object",
- "properties": {
- "fulfillmentType": {
- "type": "string",
- "description": "This field specifies how an eBay vault order will be fulfilled. Supported options are:- Seller to Vault: the order will be shipped by the seller to an authenticator.
- Vault to Vault: the order will be shipped from an eBay vault to the buyer's vault.
- Vault to Buyer: the order will be shipped from an eBay vault to the buyer's shipping address.
For implementation help, refer to eBay API documentation"
- }
- }
- },
- "Error": {
- "type": "object",
- "properties": {
- "category": {
- "type": "string",
- "description": "The context or source of this error or warning."
- },
- "domain": {
- "type": "string",
- "description": "The name of the domain containing the service or application. For example, sell is a domain."
- },
- "errorId": {
- "type": "integer",
- "description": "A positive integer that uniquely identifies the specific error condition that occurred. Your application can use these values as error code identifiers in your customized error-handling algorithms.",
- "format": "int32"
- },
- "inputRefIds": {
- "type": "array",
- "description": "A list of one or more specific request elements (if any) associated with the error or warning. The format of these strings depends on the request payload format. For JSON, use JSONPath notation.",
- "items": {
- "type": "string"
- }
- },
- "longMessage": {
- "type": "string",
- "description": "An expanded version of the message field.
Maximum length: 200 characters"
- },
- "message": {
- "type": "string",
- "description": "A message about the error or warning which is device agnostic and readable by end users and application developers. It explains what the error or warning is, and how to fix it (in a general sense). If applicable, the value is localized to the end user's requested locale.
Maximum length: 50 characters"
- },
- "outputRefIds": {
- "type": "array",
- "description": "A list of one or more specific response elements (if any) associated with the error or warning. The format of these strings depends on the request payload format. For JSON, use JSONPath notation.",
- "items": {
- "type": "string"
- }
- },
- "parameters": {
- "type": "array",
- "description": "Contains a list of name-value pairs that provide additional information concerning this error or warning. Each item in the list is an input parameter that contributed to the error or warning condition.",
- "items": {
- "$ref": "#/components/schemas/ErrorParameter"
- }
- },
- "subdomain": {
- "type": "string",
- "description": "The name of the domain's subsystem or subdivision. For example, fulfillment is a subdomain in the sell domain."
- }
- },
- "description": "This type contains a error or warning related to a call request. "
- },
- "ErrorParameter": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "This is the name of input field that caused an issue with the call request."
- },
- "value": {
- "type": "string",
- "description": "This is the actual value that was passed in for the element specified in the name field."
- }
- },
- "description": "This type contains the name and value of an input parameter that contributed to a specific error or warning condition."
- },
- "EvidenceRequest": {
- "type": "object",
- "properties": {
- "evidenceId": {
- "type": "string",
- "description": "Unique identifier of the evidential file set. Potentially, each evidential file set can have more than one file, that is why there is this file set identifier, and then an identifier for each file within this file set."
- },
- "evidenceType": {
- "type": "string",
- "description": "This enumeration value shows the type of evidential document provided. For implementation help, refer to eBay API documentation"
- },
- "lineItems": {
- "type": "array",
- "description": "This array shows one or more order line items associated with the evidential document that has been provided.",
- "items": {
- "$ref": "#/components/schemas/OrderLineItems"
- }
- },
- "requestDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when eBay requested the evidential document from the seller in response to a payment dispute.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- },
- "respondByDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when the seller is expected to provide a requested evidential document to eBay.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- }
- },
- "description": "This type is used by the evidenceRequests array that is returned in the getPaymentDispute response if one or more evidential documents are being requested to help resolve the payment dispute."
- },
- "ExtendedContact": {
- "type": "object",
- "properties": {
- "companyName": {
- "type": "string",
- "description": "The company name associated with the buyer or eBay shipping partner. This field is only returned if defined/applicable to the buyer or eBay shipping partner."
- },
- "contactAddress": {
- "description": "This container shows the shipping address of the buyer or eBay shipping partner.",
- "$ref": "#/components/schemas/Address"
- },
- "email": {
- "type": "string",
- "description": "This field contains the email address of the buyer. This address will be returned for up to 14 days from order creation. If an order is more than 14 days old, no address is returned.
Note: If returned, this field contains the email address of the buyer, even for Global Shipping Program shipments.
The email will not be returned for any order that is more than 90 days old."
- },
- "fullName": {
- "type": "string",
- "description": "The full name of the buyer or eBay shipping partner.
Note: The fullName will not be returned for any order that is more than 90 days old."
- },
- "primaryPhone": {
- "description": "The primary telephone number of the buyer or eBay shipping partner.
Note: The primaryPhone will not be returned for any order that is more than 90 days old.",
- "$ref": "#/components/schemas/PhoneNumber"
- }
- },
- "description": "This type contains shipping and contact information for a buyer or an eBay shipping partner."
- },
- "FileEvidence": {
- "type": "object",
- "properties": {
- "fileId": {
- "type": "string",
- "description": "This field is used to identify the evidence file to be uploaded to the evidence set.
This file is created with the uploadEvidenceFile method and can be retrieved using the getPaymentDisputes method."
- }
- },
- "description": "This type is used to store the unique identifier of an evidence file. Evidence files are used by seller to contest a payment dispute."
- },
- "FileInfo": {
- "type": "object",
- "properties": {
- "fileId": {
- "type": "string",
- "description": "The unique identifier of the evidence file."
- },
- "fileType": {
- "type": "string",
- "description": "The type of file uploaded. Supported file extensions are .JPEG, .JPG, and .PNG., and maximum file size allowed is 1.5 MB."
- },
- "name": {
- "type": "string",
- "description": "The seller-provided name of the evidence file."
- },
- "uploadedDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when the seller uploaded the evidential document to eBay.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- }
- },
- "description": "This type is used by the files array, which shows the name, ID, file type, and upload date for each provided evidential file."
- },
- "FulfillmentStartInstruction": {
- "type": "object",
- "properties": {
- "appointment": {
- "description": "This container provides information used by the installation provider concerning appointment details selected by the buyer.",
- "$ref": "#/components/schemas/AppointmentDetails"
- },
- "ebaySupportedFulfillment": {
- "type": "boolean",
- "description": "This field is only returned if its value is true and indicates that the fulfillment will be shipped via eBay's Global Shipping Program, eBay International Shipping, or the Authenticity Guarantee service program.
For more information, see the Global Shipping Program help topic."
- },
- "finalDestinationAddress": {
- "description": "This container is only returned if the value of ebaySupportedFulfillment field is true.
This is the final destination address for a Global Shipping Program shipment or an eBay International Shipping shipment, which is usually the recipient's home. Sellers should not ship directly to this address; instead they should ship this package to their international shipping provider's domestic warehouse. The international shipping provider is responsible for delivery to the final destination address.
For more information, see Addressing Shipments. Note: For Authenticity Guarantee program shipment, this is the address of the authenticator's warehouse. The authenticator is responsible for delivery to the buyer shipping address.
",
- "$ref": "#/components/schemas/Address"
- },
- "fulfillmentInstructionsType": {
- "type": "string",
- "description": "The enumeration value returned in this field indicates the method of fulfillment that will be used to deliver this set of line items (this package) to the buyer. This field will have a value of SHIP_TO if the ebaySupportedFulfillment field is returned with a value of true. See the FulfillmentInstructionsType definition for more information about different fulfillment types. For implementation help, refer to eBay API documentation"
- },
- "maxEstimatedDeliveryDate": {
- "type": "string",
- "description": "This is the estimated latest date that the fulfillment will be completed. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned ifthe value of the fulfillmentInstructionsType field is DIGITAL or PREPARE_FOR_PICKUP.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "minEstimatedDeliveryDate": {
- "type": "string",
- "description": "This is the estimated earliest date that the fulfillment will be completed. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned if the value of the fulfillmentInstructionsType field is DIGITAL or PREPARE_FOR_PICKUP.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "pickupStep": {
- "description": "This container is only returned for In-Store Pickup orders, and it indicates the specific merchant's store where the buyer will pick up the order. The In-Store Pickup feature is supported in the US, Canada, UK, Germany, and Australia marketplaces.",
- "$ref": "#/components/schemas/PickupStep"
- },
- "shippingStep": {
- "description": "This container consists of shipping information for this fulfillment, including the shipping carrier, the shipping service option, and the shipment destination. This container is not returned if the value of the fulfillmentInstructionsType field is DIGITAL, or for In-Store Pickup orders.
For Click and Collect orders, the shipping destination will be a brick-and-mortar store where the buyer will pick up the order.",
- "$ref": "#/components/schemas/ShippingStep"
- }
- },
- "description": "This type contains a set of specifications for processing a fulfillment of an order, including the type of fulfillment, shipping carrier and service, addressing details, and estimated delivery window. These instructions are derived from the buyer's and seller's eBay account preferences, the listing parameters, and the buyer's checkout selections. The seller can use them as a starting point for packaging, addressing, and shipping the order."
- },
- "GiftDetails": {
- "type": "object",
- "properties": {
- "message": {
- "type": "string",
- "description": "This field contains the gift message from the buyer to the gift recipient. This field is only returned if the buyer of the gift included a message for the gift.
Note: The message will not be returned for any order that is more than 90 days old."
- },
- "recipientEmail": {
- "type": "string",
- "description": "The email address of the gift recipient. The seller will send the digital gift card to this email address.
Note: The recipientEmail will not be returned for any order that is more than 90 days old."
- },
- "senderName": {
- "type": "string",
- "description": "The name of the buyer, which will appear on the email that is sent to the gift recipient.
Note: The senderName will not be returned for any order that is more than 90 days old."
- }
- },
- "description": "This type contains information about a digital gift card line item that was purchased as a gift and sent to the recipient by email.
Note: GiftDetails will not be returned for any order that is more than 90 days old."
- },
- "InfoFromBuyer": {
- "type": "object",
- "properties": {
- "contentOnHold": {
- "type": "boolean",
- "description": "When the value of this field is true it indicates that the buyer's note regarding the payment dispute (i.e., the buyerProvided.note field,) is on hold. When this is the case, the buyerProvided.note field will not be returned.
When the value of this field is false, it is not returned."
- },
- "note": {
- "type": "string",
- "description": "This field shows any note that was left by the buyer in regard to the dispute."
- },
- "returnShipmentTracking": {
- "type": "array",
- "description": "This array shows shipment tracking information for one or more shipping packages being returned to the buyer after a payment dispute.",
- "items": {
- "$ref": "#/components/schemas/TrackingInfo"
- }
- }
- },
- "description": "This container is returned if the buyer is returning one or more line items in an order that is associated with the payment dispute, and that buyer has provided return shipping tracking information and/or a note about the return."
- },
- "IssueRefundRequest": {
- "type": "object",
- "properties": {
- "reasonForRefund": {
- "type": "string",
- "description": "The enumeration value passed into this field indicates the reason for the refund. One of the defined enumeration values in the ReasonForRefundEnum type must be used.
This field is required, and it is highly recommended that sellers use the correct refund reason, especially in the case of a buyer-requested cancellation or 'buyer remorse' return to indicate that there was nothing wrong with the item(s) or with the shipment of the order.
Note: If issuing refunds for more than one order line item, keep in mind that the refund reason must be the same for each of the order line items. If the refund reason is different for one or more order line items in an order, the seller would need to make separate issueRefund calls, one for each refund reason. For implementation help, refer to eBay API documentation"
- },
- "comment": {
- "type": "string",
- "description": "This free-text field allows the seller to clarify why the refund is being issued to the buyer.
Max Length: 100"
- },
- "refundItems": {
- "type": "array",
- "description": "The refundItems array is only required if the seller is issuing a refund for one or more individual order line items in a multiple line item order. Otherwise, the seller just uses the orderLevelRefundAmount container to specify the amount of the refund for the entire order.",
- "items": {
- "$ref": "#/components/schemas/RefundItem"
- }
- },
- "orderLevelRefundAmount": {
- "description": "This container is used to specify the amount of the refund for the entire order. If a seller wants to issue a refund for an individual line item within a multiple line item order, the seller would use the refundItems array instead.",
- "$ref": "#/components/schemas/SimpleAmount"
- }
- },
- "description": "The base type used by the request payload of the issueRefund method."
- },
- "ItemLocation": {
- "type": "object",
- "properties": {
- "countryCode": {
- "type": "string",
- "description": "The two-letter ISO 3166 code representing the country of the address. For implementation help, refer to eBay API documentation"
- },
- "location": {
- "type": "string",
- "description": "Indicates the geographical location of the item (along with the values in the countryCode and postalCode fields).
Note: If the item is shipped from a fulfillment center location through the Multi-Warehouse Program, this field will return the geographical location of the fulfillment center closest to the buyer.
This field provides city, province, state, or similar information."
- },
- "postalCode": {
- "type": "string",
- "description": "The postal code of the address."
- }
- },
- "description": "This type describes the physical location of an order."
- },
- "LegacyReference": {
- "type": "object",
- "properties": {
- "legacyItemId": {
- "type": "string",
- "description": "The unique identifier of a listing.
This value can be found in the Transaction container in the response of the getOrder call of the Trading API.
Note: Both legacyItemId and legacyTransactionId are needed to identify an order line item. "
- },
- "legacyTransactionId": {
- "type": "string",
- "description": "The unique identifier of a sale/transaction in legacy/Trading API format. A 'transaction ID' is created once a buyer purchases a 'Buy It Now' item or if an auction listing ends with a winning bidder.
This value can be found in the Transaction container in the response of the getOrder call of the Trading API.
Note: Both legacyItemId and legacyTransactionId are needed to identify an order line item. "
- }
- },
- "description": "Type defining the legacyReference container. This container is needed if the seller is issuing a refund for an individual order line item, and wishes to use an item ID and transaction ID to identify the order line item."
- },
- "LineItem": {
- "type": "object",
- "properties": {
- "appliedPromotions": {
- "type": "array",
- "description": "This array contains information about one or more sales promotions or discounts applied to the line item. It is always returned, but will be returned as an empty array if no special sales promotions or discounts apply to the order line item.",
- "items": {
- "$ref": "#/components/schemas/AppliedPromotion"
- }
- },
- "compatibilityProperties": {
- "type": "array",
- "description": "This array is only returned for a Parts & Accessory item, and identifies the buyer's motor vehicle that is compatible with the part or accessory.",
- "items": {
- "$ref": "#/components/schemas/Property"
- }
- },
- "deliveryCost": {
- "description": "This container consists of a breakdown of all costs associated with the fulfillment of the line item.",
- "$ref": "#/components/schemas/DeliveryCost"
- },
- "discountedLineItemCost": {
- "description": "The cost of the line item after applying any discounts. This container is only returned if the order line item was discounted through a promotion.",
- "$ref": "#/components/schemas/Amount"
- },
- "ebayCollectAndRemitTaxes": {
- "type": "array",
- "description": "This container will be returned if the order line item is subject to a 'Collect and Remit' tax that eBay will collect and remit to the proper taxing authority on the buyer's behalf.
'Collect and Remit' tax includes:- US state-mandated sales tax
- Federal and Provincial Sales Tax in Canada
- 'Goods and Services' tax in Canada, Australia, New Zealand, and Jersey
- VAT collected for the UK, EU countries, Kazakhstan, and Belarus
- Sales & Service Tax (SST) in Malaysia
The amount of this tax is shown in the amount field, and the type of tax is shown in the taxType field.
eBay will display the tax type and amount during checkout in accordance with the buyer's address, and handle collection and remittance of the tax without requiring the seller to take any action.",
- "items": {
- "$ref": "#/components/schemas/EbayCollectAndRemitTax"
- }
- },
- "ebayCollectedCharges": {
- "description": "This container consists of a breakdown of costs that are collected by eBay from the buyer for this order.
Note: Currently, this container is returned only if eBay is directly charging the buyer for eBay shipping.",
- "$ref": "#/components/schemas/EbayCollectedCharges"
- },
- "giftDetails": {
- "description": "This container consists of information that is needed by the seller to send a digital gift card to the buyer, or recipient of the digital gift card. This container is only returned and applicable for digital gift card line items.",
- "$ref": "#/components/schemas/GiftDetails"
- },
- "itemLocation": {
- "description": "This container field describes the physical location of the order line item.
Note: If the item is shipped from a fulfillment center location through the Multi-Warehouse Program, this container will return the location details of the fulfillment center closest to the buyer.",
- "$ref": "#/components/schemas/ItemLocation"
- },
- "legacyItemId": {
- "type": "string",
- "description": "The eBay-generated legacy listing item ID of the listing. Note that the unique identifier of a listing in REST-based APIs is called the listingId instead."
- },
- "legacyVariationId": {
- "type": "string",
- "description": "The unique identifier of a single variation within a multiple-variation listing. This field is only returned if the line item purchased was from a multiple-variation listing."
- },
- "lineItemCost": {
- "description": "The selling price of the line item before applying any discounts. The value of this field is calculated by multiplying the single unit price by the number of units purchased (value of the quantity field).",
- "$ref": "#/components/schemas/Amount"
- },
- "lineItemFulfillmentInstructions": {
- "description": "This container consists of information related to shipping dates and expectations, including the 'ship-by date' and expected delivery windows that are based on the seller's stated handling time and the shipping service option that will be used. These fields provide guidance on making sure expected delivery dates are made, whether the order is a eBay Guaranteed Delivery order or a non-guaranteed delivery order.",
- "$ref": "#/components/schemas/LineItemFulfillmentInstructions"
- },
- "lineItemFulfillmentStatus": {
- "type": "string",
- "description": "This enumeration value indicates the current fulfillment status of the line item. For implementation help, refer to eBay API documentation"
- },
- "lineItemId": {
- "type": "string",
- "description": "This is the unique identifier of an eBay order line item. This field is created as soon as there is a commitment to buy from the seller."
- },
- "linkedOrderLineItems": {
- "type": "array",
- "description": "An array of one or more line items related to the corresponding order, but not a part of that order. Details include the order ID, line item ID, and title of the linked line item, the seller of that item, item specifics, estimated delivery times, and shipment tracking (if available).",
- "items": {
- "$ref": "#/components/schemas/LinkedOrderLineItem"
- }
- },
- "listingMarketplaceId": {
- "type": "string",
- "description": "The unique identifier of the eBay marketplace where the line item was listed. For implementation help, refer to eBay API documentation"
- },
- "properties": {
- "description": "Contains information about the eBay programs, if any, under which the line item was listed.",
- "$ref": "#/components/schemas/LineItemProperties"
- },
- "purchaseMarketplaceId": {
- "type": "string",
- "description": "The unique identifier of the eBay marketplace where the line item was listed. Often, the listingMarketplaceId and the purchaseMarketplaceId identifier are the same, but there are occasions when an item will surface on multiple eBay marketplaces. For implementation help, refer to eBay API documentation"
- },
- "quantity": {
- "type": "integer",
- "description": "The number of units of the line item in the order. These are represented as a group by a single lineItemId.",
- "format": "int32"
- },
- "refunds": {
- "type": "array",
- "description": "This array is always returned, but is returned as an empty array unless the seller has submitted a partial or full refund to the buyer for the order. If a refund has occurred, the refund amount and refund date will be shown for each refund.",
- "items": {
- "$ref": "#/components/schemas/LineItemRefund"
- }
- },
- "sku": {
- "type": "string",
- "description": "Seller-defined Stock-Keeping Unit (SKU). This inventory identifier must be unique within the seller's eBay inventory. SKUs are optional when listing in the legacy/Trading API system, but SKUs are required when listing items through the Inventory API model."
- },
- "soldFormat": {
- "type": "string",
- "description": "The eBay listing type of the line item. The most common listing types are AUCTION and FIXED_PRICE. For implementation help, refer to eBay API documentation"
- },
- "taxes": {
- "type": "array",
- "description": "Contains a list of taxes applied to the line item, if any. This array is always returned, but will be returned as empty if no taxes are applicable to the line item.",
- "items": {
- "$ref": "#/components/schemas/Tax"
- }
- },
- "title": {
- "type": "string",
- "description": "The title of the listing.
Note: The Item ID value for the listing will be returned in this field instead of the actual title if this particular listing is on-hold due to an eBay policy violation."
- },
- "total": {
- "description": "This is the total price that the buyer must pay for the line item after all costs (item cost, delivery cost, taxes,) are added, minus any discounts and/or promotions.
Note: For orders that are subject to 'eBay Collect and Remit' tax, the 'Collect and Remit' tax amount for the order will be included in this total value only when the fieldGroups query parameter is set to TAX_BREAKDOWN. If the fieldGroups query parameter is not set to TAX_BREAKDOWN, 'Collect and Remit' will not be added into this total value.
To determine if 'Collect and Remit' taxes were added into this total value, the user can check for the corresponding lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is in this amount:STATE_SALES_TAX: US state-mandated sales taxPROVINCE_SALES_TAX: Provincial Sales Tax in CanadaGST: 'Goods and Services' tax in Canada, Australia, and New ZealandVAT: VAT collected for UK and EU countries
",
- "$ref": "#/components/schemas/Amount"
- },
- "variationAspects": {
- "type": "array",
- "description": "An array of aspect name-value pairs that identifies the specific variation of a multi-variation listing. This array can contain multiple name-value pairs, such as color:blue and size:large, and will only be returned for orders created from a multiple-variation listing.",
- "items": {
- "$ref": "#/components/schemas/NameValuePair"
- }
- }
- },
- "description": "This type contains the details of each line item in an order."
- },
- "LineItemFulfillmentInstructions": {
- "type": "object",
- "properties": {
- "guaranteedDelivery": {
- "type": "boolean",
- "description": "Although this field is still returned, it can be ignored since eBay Guaranteed Delivery is no longer a supported feature on any marketplace. This field may get removed from the schema in the future."
- },
- "maxEstimatedDeliveryDate": {
- "type": "string",
- "description": "The estimated latest date and time that the buyer can expect to receive the line item based on the seller's stated handling time and the transit times of the available shipping service options. The seller must pay extra attention to this date, as a failure to deliver by this date/time can result in a 'Late shipment' seller defect, and can affect seller level and Top-Rated Seller status. In addition to the seller defect, buyers will be eligible for a shipping cost refund, and will also be eligible to return the item for a full refund (with no return shipping charge) if they choose.
Note: This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "minEstimatedDeliveryDate": {
- "type": "string",
- "description": "The estimated earliest date and time that the buyer can expect to receive the line item based on the seller's stated handling time and the transit times of the available shipping service options.
Note: This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "shipByDate": {
- "type": "string",
- "description": "The latest date and time by which the seller should ship line item in order to meet the expected delivery window. This timestamp will be set by eBay based on time of purchase and the seller's stated handling time. The seller must pay extra attention to this date, as a failure to physically ship the line item by this date/time can result in a 'Late shipment' seller defect, and can affect seller level and Top-Rated Seller status. In addition to the seller defect, buyers will be eligible for a shipping cost refund, and will also be eligible to return the item for a full refund (with no return shipping charge) if they choose.
Note: This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- }
- },
- "description": "This type contains the specifications for processing the fulfillment of a line item, including the handling window and the delivery window. These fields provide guidance for eBay Guaranteed Delivery as well as for non-guaranteed delivery."
- },
- "LineItemProperties": {
- "type": "object",
- "properties": {
- "buyerProtection": {
- "type": "boolean",
- "description": "A value of true indicates that the line item is covered by eBay's Buyer Protection program."
- },
- "fromBestOffer": {
- "type": "boolean",
- "description": "This field is only returned if true and indicates that the purchase occurred by the buyer and seller mutually agreeing on a Best Offer amount. The Best Offer feature can be set up for any listing type, but if this feature is set up for an auction listing, it will no longer be available once a bid has been placed on the listing."
- },
- "soldViaAdCampaign": {
- "type": "boolean",
- "description": "This field is only returned if true and indicates that the line item was sold as a result of a seller's ad campaign."
- }
- },
- "description": "This type contains information about the eBay programs under which a line item was listed and sold."
- },
- "LineItemReference": {
- "type": "object",
- "properties": {
- "lineItemId": {
- "type": "string",
- "description": "This is the unique identifier of the eBay order line item that is part of the shipping fulfillment.
Line item Ids can be found in the lineItems.lineItemId field of the getOrders response."
- },
- "quantity": {
- "type": "integer",
- "description": "This is the number of lineItems associated with the trackingNumber specified by the seller. This must be a whole number greater than zero (0).
Default: 1",
- "format": "int32"
- }
- },
- "description": "This type identifies the line item and quantity of that line item that comprises one fulfillment, such as a shipping package."
- },
- "LineItemRefund": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "This field shows the refund amount for a line item. This field is only returned if the buyer is due a refund for the line item.
Note: The refund amount shown is the seller's net amount received from the sale/transaction. eBay-collected tax will not be included in this amount, so the actual amount of the buyer's refund may be higher than this value.",
- "$ref": "#/components/schemas/Amount"
- },
- "refundDate": {
- "type": "string",
- "description": "The date and time that the refund was issued for the line item. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the refund has been issued.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "refundId": {
- "type": "string",
- "description": "Unique identifier of a refund that was initiated for an order's line item through the issueRefund method. If the issueRefund method was used to issue a refund at the order level, this identifier is returned at the order level instead (paymentSummary.refunds.refundId field).
A refundId value is returned in the response of the issueRefund method, and this same value will be returned in the getOrder and getOrders responses for pending and completed refunds."
- },
- "refundReferenceId": {
- "type": "string",
- "description": "This field is reserved for internal or future use."
- }
- },
- "description": "This type contains refund information for a line item."
- },
- "LinkedOrderLineItem": {
- "type": "object",
- "properties": {
- "lineItemAspects": {
- "type": "array",
- "description": "This array contains the complete set of items aspects for the linked line item. For example:
\"lineItemAspects\": [
{
\"name\": \"Tire Type\",
\"value\": \"All Season\"
},
...
{
\"name\": \"Car Type\",
\"value\": \"Performance\"
}
]
Note: All item specifics for the listing are returned. The name/value pairs returned are in the language of the linked line item's listing site, which may vary from the seller's language.",
- "items": {
- "$ref": "#/components/schemas/NameValuePair"
- }
- },
- "lineItemId": {
- "type": "string",
- "description": "The unique identifier of the linked order line item."
- },
- "maxEstimatedDeliveryDate": {
- "type": "string",
- "description": "The end of the date range in which the linked line item is expected to be delivered to the shipping address."
- },
- "minEstimatedDeliveryDate": {
- "type": "string",
- "description": "The beginning of the date range in which the linked line item is expected to be delivered to the shipping address."
- },
- "orderId": {
- "type": "string",
- "description": "The unique identifier of the order to which the linked line item belongs."
- },
- "sellerId": {
- "type": "string",
- "description": "The eBay user ID of the seller who sold the linked line item. For example, the user ID of the tire seller."
- },
- "shipments": {
- "type": "array",
- "description": "An array containing any shipment tracking information available for the linked line item.",
- "items": {
- "$ref": "#/components/schemas/TrackingInfo"
- }
- },
- "title": {
- "type": "string",
- "description": "The listing title of the linked line item.
Note: The Item ID value for the listing will be returned in this field instead of the actual title if this particular listing is on-hold due to an eBay policy violation."
- }
- },
- "description": "This type contains data on a line item that is related to, but not a part of the order."
- },
- "MonetaryTransaction": {
- "type": "object",
- "properties": {
- "date": {
- "type": "string",
- "description": "This timestamp indicates when the monetary transaction occurred. A date is returned for all monetary transactions.
The following format is used: YYYY-MM-DDTHH:MM:SS.SSSZ. For example, 2015-08-04T19:09:02.768Z."
- },
- "type": {
- "type": "string",
- "description": "This enumeration value indicates whether the monetary transaction is a charge or a credit to the seller. For implementation help, refer to eBay API documentation"
- },
- "reason": {
- "type": "string",
- "description": "This enumeration value indicates the reason for the monetary transaction. For implementation help, refer to eBay API documentation"
- },
- "amount": {
- "description": "The amount involved in the monetary transaction. For active cross-border trade orders, the currency conversion and exchangeRate fields will be displayed as well.",
- "$ref": "#/components/schemas/DisputeAmount"
- }
- },
- "description": "This type is used to provide details about one or more monetary transactions that occur as part of a payment dispute."
- },
- "NameValuePair": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "The text representing the name of the aspect for the name-value pair. For example, color, or Tire Type."
- },
- "value": {
- "type": "string",
- "description": "The value of the aspect for the name-value pair. For example, red, or All Season."
- }
- },
- "description": "This type contains the name-value specifics of a multi-variation listing (variationAspects) or the name-value specifics for all item aspects of a linked line item (linkedOrderLineItems)."
- },
- "Order": {
- "type": "object",
- "properties": {
- "buyer": {
- "description": "This container consists of information about the order's buyer. At this time, only the buyer's eBay user ID is returned, but it's possible that more buyer information can be added to this container in the future.",
- "$ref": "#/components/schemas/Buyer"
- },
- "buyerCheckoutNotes": {
- "type": "string",
- "description": "This field contains any comments that the buyer left for the seller about the order during checkout process. This field is only returned if a buyer left comments at checkout time. "
- },
- "cancelStatus": {
- "description": "This container consists of order cancellation information if a cancel request has been made. This container is always returned, and if no cancel request has been made, the cancelState field is returned with a value of NONE_REQUESTED, and an empty cancelRequests array is also returned.",
- "$ref": "#/components/schemas/CancelStatus"
- },
- "creationDate": {
- "type": "string",
- "description": "The date and time that the order was created. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "ebayCollectAndRemitTax": {
- "type": "boolean",
- "description": "This field is only returned if true, and indicates that eBay will collect tax (US state-mandated sales tax, Federal and Provincial Sales Tax in Canada, 'Goods and Services' tax in Canada, Australia, and New Zealand, and VAT collected for UK and EU countries,) for at least one line item in the order, and remit the tax to the taxing authority of the buyer's residence. If this field is returned, the seller should search for one or more ebayCollectAndRemitTaxes containers at the line item level to get more information about the type of tax and the amount."
- },
- "fulfillmentHrefs": {
- "type": "array",
- "description": "This array contains a list of one or more getShippingFulfillment call URIs that can be used to retrieve shipping fulfillments that have been set up for the order.",
- "items": {
- "type": "string"
- }
- },
- "fulfillmentStartInstructions": {
- "type": "array",
- "description": "This container consists of a set of specifications for fulfilling the order, including the type of fulfillment, shipping carrier and service, shipping address, and estimated delivery window. These instructions are derived from the buyer's and seller's eBay account preferences, the listing parameters, and the buyer's checkout selections. The seller can use them as a starting point for packaging, addressing, and shipping the order.
Note: Although this container is presented as an array, it currently returns only one set of fulfillment specifications. Additional array members will be supported in future functionality.",
- "items": {
- "$ref": "#/components/schemas/FulfillmentStartInstruction"
- }
- },
- "lastModifiedDate": {
- "type": "string",
- "description": "The date and time that the order was last modified. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "lineItems": {
- "type": "array",
- "description": "This array contains the details for all line items that comprise the order.",
- "items": {
- "$ref": "#/components/schemas/LineItem"
- }
- },
- "orderFulfillmentStatus": {
- "type": "string",
- "description": "The degree to which fulfillment of the order is complete. See the OrderFulfillmentStatus type definition for more information about each possible fulfillment state. For implementation help, refer to eBay API documentation"
- },
- "orderId": {
- "type": "string",
- "description": "The unique identifier of the order. This field is always returned."
- },
- "orderPaymentStatus": {
- "type": "string",
- "description": "The enumeration value returned in this field indicates the current payment status of an order, or in case of a refund request, the current status of the refund. See the OrderPaymentStatusEnum type definition for more information about each possible payment/refund state. For implementation help, refer to eBay API documentation"
- },
- "paymentSummary": {
- "description": "This container consists of detailed payment information for the order, including buyer payment for the order, refund information (if applicable), and seller payment holds (if applicable).",
- "$ref": "#/components/schemas/PaymentSummary"
- },
- "pricingSummary": {
- "description": "This container consists of a summary of cumulative costs and charges for all line items of an order, including item price, price adjustments, sales taxes, delivery costs, and order discounts.",
- "$ref": "#/components/schemas/PricingSummary"
- },
- "program": {
- "description": "This container is returned for orders that are eligible for eBay's Authenticity Guarantee service. The seller ships Authenticity Guarantee service items to the authentication partner instead of the buyer. The authenticator address is found in the fulfillmentStartInstructions.shippingStep.shipTo container. If the item is successfully authenticated, the authenticator will ship the item to the buyer.",
- "$ref": "#/components/schemas/Program"
- },
- "salesRecordReference": {
- "type": "string",
- "description": "An eBay-generated identifier that is used to identify and manage orders through the Selling Manager and Selling Manager Pro tools. This order identifier can also be found on the Orders grid page and in the Sales Record pages in Seller Hub. A salesRecordReference number is only generated and returned at the order level, and not at the order line item level.
In cases where the seller does not have a Selling Manager or Selling Manager Pro subscription nor access to Seller Hub, this field may not be returned."
- },
- "sellerId": {
- "type": "string",
- "description": "The unique eBay user ID of the seller who sold the order."
- },
- "totalFeeBasisAmount": {
- "description": "This is the cumulative base amount used to calculate the final value fees for each order. The final value fees are deducted from the seller payout associated with the order. Final value fees are calculated as a percentage of order cost (item cost + shipping cost) and the percentage rate can vary by eBay category. ",
- "$ref": "#/components/schemas/Amount"
- },
- "totalMarketplaceFee": {
- "description": "This is the cumulative fees accrued for the order and deducted from the seller payout.",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type contains the details of an order, including information about the buyer, order history, shipping fulfillments, line items, costs, payments, and order fulfillment status."
- },
- "OrderLineItems": {
- "type": "object",
- "properties": {
- "itemId": {
- "type": "string",
- "description": "The unique identifier of the eBay listing associated with the order."
- },
- "lineItemId": {
- "type": "string",
- "description": "The unique identifier of the line item within the order."
- }
- },
- "description": "This type is used by the lineItems array that is used to identify one or more line items in the order with the payment dispute."
- },
- "OrderRefund": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "This field shows the refund amount for an order. This container is always returned for each refund.
Note: The refund amount shown is the seller's net amount received from the sale/transaction. eBay-collected tax will not be included in this amount, so the actual amount of the buyer's refund may be higher than this value.",
- "$ref": "#/components/schemas/Amount"
- },
- "refundDate": {
- "type": "string",
- "description": "The date and time that the refund was issued. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the refund has been issued.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "refundId": {
- "type": "string",
- "description": "Unique identifier of a refund that was initiated for an order through the issueRefund method. If the issueRefund method was used to issue one or more refunds at the line item level, these refund identifiers are returned at the line item level instead (lineItems.refunds.refundId field).
A refundId value is returned in the response of the issueRefund method, and this same value will be returned in the getOrders and getOrders responses for pending and completed refunds. For other refunds, see the refundReferenceId field."
- },
- "refundReferenceId": {
- "type": "string",
- "description": "The eBay-generated unique identifier for the refund. This field is not returned until the refund has been issued."
- },
- "refundStatus": {
- "type": "string",
- "description": "This enumeration value indicates the current status of the refund to the buyer. This container is always returned for each refund. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type contains information about a refund issued for an order. This does not include line item level refunds."
- },
- "OrderSearchPagedCollection": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the getOrders call request that produced the current page of the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The maximum number of orders returned per page of the result set. The limit value can be passed in as a query parameter, or if omitted, its value defaults to 50.
Note: If this is the last or only page of the result set, the page may contain fewer orders than the limit value. To determine the number of pages in a result set, divide the total value (total number of orders matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total orders) and the limit value was 50 (show 50 orders per page), the total number of pages in the result set is three, so the seller would have to make three separate getOrders calls to view all orders matching the input criteria. Default: 50",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The getOrders call URI to use if you wish to view the next page of the result set. For example, the following URI returns records 41 thru 50 from the collection of orders:
path/order?limit=10&offset=40
This field is only returned if there is a next page of results to view based on the current input criteria.
"
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
- "format": "int32"
- },
- "orders": {
- "type": "array",
- "description": "This array contains one or more orders that are part of the current result set, that is controlled by the input criteria. The details of each order include information about the buyer, order history, shipping fulfillments, line items, costs, payments, and order fulfillment status.
By default, orders are returned according to creation date (oldest to newest), but the order will vary according to any filter that is set in request.",
- "items": {
- "$ref": "#/components/schemas/Order"
- }
- },
- "prev": {
- "type": "string",
- "description": "The getOrders call URI for the previous result set. For example, the following URI returns orders 21 thru 30 from the collection of orders:
path/order?limit=10&offset=20
This field is only returned if there is a previous page of results to view based on the current input criteria."
- },
- "total": {
- "type": "integer",
- "description": "The total number of orders in the results set based on the current input criteria.
Note: If no orders are found, this field is returned with a value of 0.",
- "format": "int32"
- },
- "warnings": {
- "type": "array",
- "description": "This array is returned if one or more errors or warnings occur with the call request.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type contains the specifications for the collection of orders that match the search or filter criteria of a getOrders call. The collection is grouped into a result set, and based on the query parameters that are set (including the limit and offset parameters), the result set may included multiple pages, but only one page of the result set can be viewed at a time."
- },
- "Payment": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "The amount that seller receives for the order via the payment method mentioned in Payment.paymentMethod.
Note: For orders that are subject to 'eBay Collect and Remit' tax, which includes US state-mandated sales tax, Federal and Provincial Sales Tax in Canada, 'Good and Services' tax in Canada, Australia, and New Zealand, and VAT collected for UK or EU, the 'Collect and Remit' tax amount for the order will be included in this amount.value field (and in the amount.convertedFromValue field if currency conversion is applicable).
To determine if 'Collect and Remit' taxes were added into this totalDueSeller value, the user can check for the corresponding lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is included in this amount:STATE_SALES_TAX: USPROVINCE_SALES_TAX: Provincial Sales Tax in CanadaGST: Canada, Australia, and New ZealandVAT: UK and EU countries
",
- "$ref": "#/components/schemas/Amount"
- },
- "paymentDate": {
- "type": "string",
- "description": "The date and time that the payment was received by the seller. This field will not be returned if buyer has yet to pay for the order. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "paymentHolds": {
- "type": "array",
- "description": "This container is only returned if eBay is temporarily holding the seller's funds for the order. If a payment hold has been placed on the order, this container includes the reason for the payment hold, the expected release date of the funds into the seller's account, the current state of the hold, and as soon as the payment hold has been released, the actual release date.",
- "items": {
- "$ref": "#/components/schemas/PaymentHold"
- }
- },
- "paymentMethod": {
- "type": "string",
- "description": "The payment method used to pay for the order. See the PaymentMethodTypeEnum type for more information on the payment methods. For implementation help, refer to eBay API documentation"
- },
- "paymentReferenceId": {
- "type": "string",
- "description": "This field is only returned if payment has been made by the buyer, and the paymentMethod is ESCROW. This field contains a special ID for ESCROW."
- },
- "paymentStatus": {
- "type": "string",
- "description": "The enumeration value returned in this field indicates the status of the payment for the order. See the PaymentStatusEnum type definition for more information on the possible payment states. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used to provide details about the seller payments for an order."
- },
- "PaymentDispute": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "This container shows the dollar value associated with the payment dispute in the currency used by the seller's marketplace.",
- "$ref": "#/components/schemas/SimpleAmount"
- },
- "availableChoices": {
- "type": "array",
- "description": "The value(s) returned in this array indicate the choices that the seller has when responding to the payment dispute. Once the seller has responded to the payment dispute, this field will no longer be shown, and instead, the sellerResponse field will show the decision that the seller made.",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- },
- "buyerProvided": {
- "description": "This container is returned if the buyer is returning one or more line items in an order that is associated with the payment dispute, and that buyer has provided return shipping tracking information and/or a note about the return.",
- "$ref": "#/components/schemas/InfoFromBuyer"
- },
- "buyerUsername": {
- "type": "string",
- "description": "This is the eBay user ID of the buyer that initiated the payment dispute."
- },
- "closedDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when the payment dispute was closed, so this field is only returned for payment disputes in the CLOSED state.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- },
- "evidence": {
- "type": "array",
- "description": "This container shows any evidence that has been provided by the seller to contest the payment dispute. Evidence may include shipment tracking information, proof of authentication documentation, image(s) to proof that an item is as described, or financial documentation/invoice.
This container is only returned if the seller has provided at least one document used as evidence against the payment dispute.",
- "items": {
- "$ref": "#/components/schemas/DisputeEvidence"
- }
- },
- "evidenceRequests": {
- "type": "array",
- "description": "This container is returned if one or more evidence documents are being requested from the seller.",
- "items": {
- "$ref": "#/components/schemas/EvidenceRequest"
- }
- },
- "lineItems": {
- "type": "array",
- "description": "This array is used to identify one or more order line items associated with the payment dispute. There will always be at least one itemId/lineItemId pair returned in this array.",
- "items": {
- "$ref": "#/components/schemas/OrderLineItems"
- }
- },
- "monetaryTransactions": {
- "type": "array",
- "description": "This array provide details about one or more monetary transactions that occur as part of a payment dispute. This array is only returned once one or more monetary transacations occur with a payment dispute.",
- "items": {
- "$ref": "#/components/schemas/MonetaryTransaction"
- }
- },
- "note": {
- "type": "string",
- "description": "This field shows information that the seller provides about the dispute, such as the basis for the dispute, any relevant evidence, tracking numbers, and so forth.
This field is limited to 1000 characters."
- },
- "openDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when the payment dispute was opened. This field is returned for payment disputes in all states.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- },
- "orderId": {
- "type": "string",
- "description": "This is the unique identifier of the order involved in the payment dispute."
- },
- "paymentDisputeId": {
- "type": "string",
- "description": "This is the unique identifier of the payment dispute. This is the same identifier that is passed in to the call URI. This identifier is automatically created by eBay once the payment dispute comes into the eBay system."
- },
- "paymentDisputeStatus": {
- "type": "string",
- "description": "The enumeration value in this field gives the current status of the payment dispute. The status of a payment dispute partially determines other fields that are returned in the response. For implementation help, refer to eBay API documentation"
- },
- "reason": {
- "type": "string",
- "description": "The enumeration value in this field gives the reason why the buyer initiated the payment dispute. See DisputeReasonEnum type for a description of the supported reasons that buyers can give for initiating a payment dispute. For implementation help, refer to eBay API documentation"
- },
- "resolution": {
- "description": "This container gives details about a payment dispute that has been resolved. This container is only returned for resolved/closed payment disputes.",
- "$ref": "#/components/schemas/PaymentDisputeOutcomeDetail"
- },
- "respondByDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when the seller must response to a payment dispute, so this field is only returned for payment disputes in the ACTION_NEEDED state. For payment disputes that currently require action by the seller, that same seller should look at the availableChoices array to see the available actions.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- },
- "returnAddress": {
- "description": "This container gives the address where the order will be returned to. This container is returned if the seller is accepting the payment dispute and will issue a refund to the buyer once the item is returned to this address.",
- "$ref": "#/components/schemas/ReturnAddress"
- },
- "revision": {
- "type": "integer",
- "description": "This integer value indicates the revision number of the payment dispute. Each time an action is taken against a payment dispute, this integer value increases by 1.",
- "format": "int32"
- },
- "sellerResponse": {
- "type": "string",
- "description": "The enumeration value returned in this field indicates how the seller has responded to the payment dispute. The seller has the option of accepting the payment dispute and agreeing to issue a refund, accepting the payment dispute and agreeing to issue a refund as long as the buyer returns the item, or contesting the payment dispute. This field is returned as soon as the seller makes an initial decision on the payment dispute. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used by the base response of the getPaymentDispute method. The getPaymentDispute method retrieves detailed information on a specific payment dispute."
- },
- "PaymentDisputeActivity": {
- "type": "object",
- "properties": {
- "activityDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time of the payment dispute activity.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- },
- "activityType": {
- "type": "string",
- "description": "This enumeration value indicates the type of activity that occured on the payment dispute. For example, a value of DISPUTE_OPENED is returned when a payment disute is first created, a value indicating the seller's decision on the dispute, such as SELLER_CONTEST, is returned when seller makes a decision to accept or contest dispute, and a value of DISPUTE_CLOSED is returned when a payment disute is resolved. See ActivityEnum for an explanation of each of the values that may be returned here. For implementation help, refer to eBay API documentation"
- },
- "actor": {
- "type": "string",
- "description": "This enumeration value indicates the actor that performed the action. Possible values include the BUYER, SELLER, CS_AGENT (eBay customer service), or SYSTEM. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used by each recorded activity on a payment dispute, from creation to resolution."
- },
- "PaymentDisputeActivityHistory": {
- "type": "object",
- "properties": {
- "activity": {
- "type": "array",
- "description": "This array holds all activities of a payment dispute, from creation to resolution. For each activity, the activity type, the actor, and a timestamp is shown. The getActivities response is dynamic, and grows with each recorded activity.",
- "items": {
- "$ref": "#/components/schemas/PaymentDisputeActivity"
- }
- }
- },
- "description": "This type is used by the base response of the getActivities method, and includes a log of all activities of a payment dispute, from creation to resolution."
- },
- "PaymentDisputeOutcomeDetail": {
- "type": "object",
- "properties": {
- "fees": {
- "description": "This container will show the dollar value of any fees associated with the payment dispute. This container is only returned if there are fees associated with the payment dispute.",
- "$ref": "#/components/schemas/SimpleAmount"
- },
- "protectedAmount": {
- "description": "This container shows the amount of money that the seller is protected against in a payment dispute under eBay's seller protection policy.",
- "$ref": "#/components/schemas/SimpleAmount"
- },
- "protectionStatus": {
- "type": "string",
- "description": "This enumeration value indicates if the seller is fully protected, partially protected, or not protected by eBay for the payment dispute. This field is always returned once the payment dispute is resolved. For implementation help, refer to eBay API documentation"
- },
- "reasonForClosure": {
- "type": "string",
- "description": "The enumeration value returned in this field indicates the outcome of the payment dispute for the seller. This field is always returned once the payment dispute is resolved. For implementation help, refer to eBay API documentation"
- },
- "recoupAmount": {
- "description": "This container shows the dollar amount being recouped from the seller. This container is empty if the seller wins the payment dispute or if the seller is fully protected by eBay's seller protection policy.",
- "$ref": "#/components/schemas/SimpleAmount"
- },
- "totalFeeCredit": {
- "description": "This container shows the amount of money in selling fee credits due back to the seller after a payment dispute is settled.",
- "$ref": "#/components/schemas/SimpleAmount"
- }
- },
- "description": "This type is used by the resolution container that is returned for payment disputes that have been resolved."
- },
- "PaymentDisputeSummary": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "This container shows the dollar value associated with the payment dispute in the currency used by the seller's marketplace. This container is returned for all payment disputes returned in the response.",
- "$ref": "#/components/schemas/SimpleAmount"
- },
- "buyerUsername": {
- "type": "string",
- "description": "This is the buyer's eBay user ID. This field is returned for all payment disputes returned in the response."
- },
- "closedDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when the payment dispute was closed, so this field is only returned for payment disputes in the CLOSED state.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- },
- "openDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when the payment dispute was opened. This field is returned for payment disputes in all states.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- },
- "orderId": {
- "type": "string",
- "description": "This is the unique identifier of the order involved in the payment dispute."
- },
- "paymentDisputeId": {
- "type": "string",
- "description": "This is the unique identifier of the payment dispute. This identifier is automatically created by eBay once the payment dispute comes into the eBay system. This identifier is passed in at the end of the getPaymentDispute call URI to retrieve a specific payment dispute. The getPaymentDispute method returns more details about a payment dispute than the getPaymentDisputeSummaries method."
- },
- "paymentDisputeStatus": {
- "type": "string",
- "description": "The enumeration value in this field gives the current status of the payment dispute. For implementation help, refer to eBay API documentation"
- },
- "reason": {
- "type": "string",
- "description": "The enumeration value in this field gives the reason why the buyer initiated the payment dispute. See DisputeReasonEnum type for a description of the supported reasons that buyers can give for initiating a payment dispute. For implementation help, refer to eBay API documentation"
- },
- "respondByDate": {
- "type": "string",
- "description": "The timestamp in this field shows the date/time when the seller must response to a payment dispute, so this field is only returned for payment disputes in the ACTION_NEEDED state. For payment disputes that require action by the seller, that same seller must call getPaymentDispute to see the next action(s) that they can take against the payment dispute.
The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z."
- }
- },
- "description": "This type is used by each payment dispute that is returned with the getPaymentDisputeSummaries method."
- },
- "PaymentHold": {
- "type": "object",
- "properties": {
- "expectedReleaseDate": {
- "type": "string",
- "description": "The date and time that the payment being held is expected to be released to the seller. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field will be returned if known by eBay.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "holdAmount": {
- "description": "The monetary amount of the payment being held. This field is always returned with the paymentHolds array. ",
- "$ref": "#/components/schemas/Amount"
- },
- "holdReason": {
- "type": "string",
- "description": "The reason that the payment is being held. A seller's payment may be held for a number of reasons, including when the seller is new, the seller's level is below standard, or if a return case or 'Significantly not as described' case is pending against the seller. This field is always returned with the paymentHolds array."
- },
- "holdState": {
- "type": "string",
- "description": "The current stage or condition of the hold. This field is always returned with the paymentHolds array.
Applicable values:HELDHELD_PENDINGNOT_HELDRELEASE_CONFIRMEDRELEASE_FAILEDRELEASE_PENDINGRELEASED
"
- },
- "releaseDate": {
- "type": "string",
- "description": "The date and time that the payment being held was actually released to the seller. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the seller's payment is actually released into the seller's account.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "sellerActionsToRelease": {
- "type": "array",
- "description": "A list of one or more possible actions that the seller can take to expedite the release of the payment hold.",
- "items": {
- "$ref": "#/components/schemas/SellerActionsToRelease"
- }
- }
- },
- "description": "This type contains information about a hold placed on a payment to a seller for an order, including the reason why the buyer's payment for the order is being held, the expected release date of the funds into the seller's account, the current state of the hold, and the actual release date if the payment has been released, and possible actions the seller can take to expedite the payout of funds into their account."
- },
- "PaymentSummary": {
- "type": "object",
- "properties": {
- "payments": {
- "type": "array",
- "description": "This array consists of payment information for the order, including payment status, payment method, payment amount, and payment date. This array is always returned, although some of the fields under this container will not be returned until payment has been made.",
- "items": {
- "$ref": "#/components/schemas/Payment"
- }
- },
- "refunds": {
- "type": "array",
- "description": "This array is always returned, but is returned as an empty array unless the seller has submitted a partial or full refund to the buyer for the order. If a refund has occurred, the refund amount and refund date will be shown for each refund.",
- "items": {
- "$ref": "#/components/schemas/OrderRefund"
- }
- },
- "totalDueSeller": {
- "description": "This is the total price that the seller receives for the entire order after all costs (item cost, delivery cost, taxes) are added for all line items, minus any discounts and/or promotions for any of the line items. Note that this value is subject to change before payment is actually made by the buyer (if the paymentStatus value was PENDING or FAILED), or if a partial or full refund occurs with the order.
Note: For orders that are subject to 'eBay Collect and Remit' tax, the 'Collect and Remit' tax amount for the order will be included in this totalDueSeller value.
To determine if 'Collect and Remit' taxes were added into this totalDueSeller value, the user can check for the corresponding lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is included in this amount:STATE_SALES_TAX: USPROVINCE_SALES_TAX: Provincial Sales Tax in CanadaGST: Canada, Australia, and New ZealandVAT: VAT collected for UK and EU countries
",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type contains information about the various monetary exchanges that apply to the net balance due for the order."
- },
- "Phone": {
- "type": "object",
- "properties": {
- "countryCode": {
- "type": "string",
- "description": " The two-letter, ISO 3166 code associated with the seller's phone number. This field is needed if the buyer is located in a different country than the seller. It is also OK to provide if the buyer and seller are both located in the same country
See CountryCodeEnum for a list of supported values."
- },
- "number": {
- "type": "string",
- "description": "The seller's primary phone number associated with the return address. When this number is provided in a contestPaymentDispute or contestPaymentDispute method, it is provided as one continuous numeric string, including the area code. So, if the phone number's area code was '408', a number in this field may look something like this:
\"number\" : \"4088084356\"
If the buyer is located in a different country than the seller, the seller's country code will need to be specified in the countryCode field."
- }
- },
- "description": "This type is used by the returnAddress
This field is always returned with the pickupStep container."
- }
- },
- "description": "This type is used to indicate the merchant's store where the buyer will pickup their In-Store Pickup order. The pickupStep container is only returned for In-Store Pickup orders. The In-Store Pickup feature is supported in the US, Canada, UK, Germany, and Australia marketplaces."
- },
- "PostSaleAuthenticationProgram": {
- "type": "object",
- "properties": {
- "outcomeReason": {
- "type": "string",
- "description": "This field indicates the result of the authenticity verification inspection on an order line item. This field is not returned when the status value of the order line item is PENDING or PASSED. The possible values returned here are NOT_AUTHENTIC, NOT_AS_DESCRIBED, CUSTOMIZED, MISCATEGORIZED, or NOT_AUTHENTIC_NO_RETURN. For implementation help, refer to eBay API documentation"
- },
- "status": {
- "type": "string",
- "description": "The value in this field indicates whether the order line item has passed or failed the authenticity verification inspection, or if the inspection and/or results are still pending. The possible values returned here are PENDING, PASSED, FAILED, or PASSED_WITH_EXCEPTION. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used to provide the status and outcome of an order line item going through the Authenticity Guarantee verification process."
- },
- "PricingSummary": {
- "type": "object",
- "properties": {
- "adjustment": {
- "description": "This container shows the total amount of any adjustments that were applied to the cost of the item(s) in the order. This amount does not include shipping, discounts, fixed fees, or taxes.
This container is only returned if price adjustments were made to the order after the initial transaction/commitment to buy occurred.",
- "$ref": "#/components/schemas/Amount"
- },
- "deliveryCost": {
- "description": "This container shows the total cost of delivering the order to the buyer, before any shipping/delivery discount is applied.",
- "$ref": "#/components/schemas/Amount"
- },
- "deliveryDiscount": {
- "description": "This container shows the total amount of delivery discounts (including shipping discounts) that apply to the order. This should be a negative real number.
This container is only returned if delivery discounts are being applied to the order.",
- "$ref": "#/components/schemas/Amount"
- },
- "fee": {
- "description": "This container shows the total amount of any special fees applied to the order, such as a tire recycling fee or an electronic waste fee.
This container is returned if special fees are being applied to the order and if the fieldGroups is set to TAX_BREAKDOWN.",
- "$ref": "#/components/schemas/Amount"
- },
- "priceDiscount": {
- "description": "This container shows the total amount of all item price discounts (including promotions) that apply to the order and reduce its cost to the buyer. This should be a negative real number.
This container is only returned if special discounts are being applied to the order.",
- "$ref": "#/components/schemas/Amount"
- },
- "priceSubtotal": {
- "description": "This container shows the cumulative costs of of all units of all line items in the order, before any discount is applied.",
- "$ref": "#/components/schemas/Amount"
- },
- "tax": {
- "description": "This container shows the total amount of tax for the order. To calculate the tax percentage rate, divide this value by the value of the total field.
This container is only returned if any type of tax (sales tax, tax on shipping, tax on handling, import tax, etc.) is applied to the order.",
- "$ref": "#/components/schemas/Amount"
- },
- "total": {
- "description": "The total cost of the order after adding all line item costs, delivery costs, sales tax, and special fees, and then subtracting all special discounts and price adjustments.
Note: For orders that are subject to 'eBay Collect and Remit' tax, the 'Collect and Remit' tax amount for the order will be included in this total value only when the fieldGroups query parameter is set to TAX_BREAKDOWN. If the fieldGroups query parameter is not set to TAX_BREAKDOWN, 'Collect and Remit' will not be added into this total value.
To determine if 'Collect and Remit' taxes were added into this total value, the user can check for the corresponding lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is included in this amount:STATE_SALES_TAX: US state-mandated sales taxPROVINCE_SALES_TAX: Provincial Sales Tax in CanadaGST: 'Good and Services' tax in Canada, Australia, and New ZealandVAT: VAT collected for UK and EU countries
",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type contains a summary of cumulative costs and charges for all line items of an order, including item price, price adjustments, sales taxes, delivery costs, and order discounts."
- },
- "Program": {
- "type": "object",
- "properties": {
- "authenticityVerification": {
- "description": "This field is returned when the third-party authenticator performs the authentication verification inspection on the order line item. Different values will be returned based on whether the item passed or failed the authentication verification inspection.",
- "$ref": "#/components/schemas/PostSaleAuthenticationProgram"
- },
- "ebayShipping": {
- "description": "This container is returned only if the order is an eBay shipping order. It consists of a field that indicates the provider of a shipping label for this order.",
- "$ref": "#/components/schemas/EbayShipping"
- },
- "ebayVault": {
- "description": "This field provides information about the eBay vault program that has been selected for an order. This is returned only for those items that are eligible for the eBay Vault Program.",
- "$ref": "#/components/schemas/EbayVaultProgram"
- },
- "ebayInternationalShipping": {
- "description": "This container is returned if the order is being fulfilled through eBay International Shipping.",
- "$ref": "#/components/schemas/EbayInternationalShipping"
- },
- "fulfillmentProgram": {
- "description": "This field provides details about an order line item being handled by eBay fulfillment. It is only returned for paid orders being fulfilled by eBay or an eBay fulfillment partner.",
- "$ref": "#/components/schemas/EbayFulfillmentProgram"
- }
- },
- "description": "This type is returned for order line items eligible for the Authenticity Guarantee service and/or for order line items fulfilled by the eBay Fulfillment program or eBay shipping."
- },
- "Property": {
- "type": "object",
- "properties": {
- "propertyDisplayName": {
- "type": "string",
- "description": "The display name of the motor vehicle aspect. This is the localized name of the compatibility property."
- },
- "propertyName": {
- "type": "string",
- "description": "The name of the motor vehicle aspect.
For example, typical vehicle property names are 'Make', 'Model', 'Year', 'Engine', and 'Trim', but will vary based on the eBay marketplace and the eBay category."
- },
- "propertyValue": {
- "type": "string",
- "description": "The value of the property specified in the propertyName field.
For example, if the propertyName is Make, then the propertyValue will be the specific make of the vehicle, such as Toyota."
- }
- },
- "description": "This type defines the property name and value for an order."
- },
- "Refund": {
- "type": "object",
- "properties": {
- "refundId": {
- "type": "string",
- "description": "The unique identifier of the order refund. This value is returned unless the refund operation fails (refundStatus value shows FAILED). This identifier can be used to track the status of the refund through a getOrder or getOrders call. For order-level refunds, check the paymentSummary.refunds.refundId field in the getOrder/getOrders response, and for line item level refunds, check the lineItems.refunds.refundId field(s) in the getOrder/getOrders response."
- },
- "refundStatus": {
- "type": "string",
- "description": "The value returned in this field indicates the success or failure of the refund operation. A successful issueRefund operation should result in a value of PENDING. A failed issueRefund operation should result in a value of FAILED, and an HTTP status code and/or and API error code may also get returned to possibly indicate the issue.
The refunds issued through this method are processed asynchronously, so the refund will not show as 'Refunded' right away. A seller will have to make a subsequent getOrder call to check the status of the refund. The status of an order refund can be found in the paymentSummary.refunds.refundStatus field of the getOrder response. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This is the base type of the issueRefund response payload. As long as the issueRefund method does not trigger an error, a response payload will be returned."
- },
- "RefundItem": {
- "type": "object",
- "properties": {
- "refundAmount": {
- "description": "This container is used to specify the amount of the refund for the corresponding order line item. If a seller wants to issue a refund for an entire order, the seller would use the orderLevelRefundAmount container instead.",
- "$ref": "#/components/schemas/SimpleAmount"
- },
- "lineItemId": {
- "type": "string",
- "description": "The unique identifier of an order line item. This identifier is created once a buyer purchases a 'Buy It Now' item or if an auction listing ends with a winning bidder.
Either this field or the legacyReference container is needed to identify an individual order line item that will receive a refund.
This value is returned using the getOrders method."
- },
- "legacyReference": {
- "description": "This container is needed if the seller is issuing a refund for an individual order line item, and wishes to use an item ID/transaction ID pair to identify the order line item.
Either this container or the lineItemId field is needed to identify an individual order line item that will receive a refund.
Note: This container should only be used if a seller is using the GetOrders method of the Trading API.",
- "$ref": "#/components/schemas/LegacyReference"
- }
- },
- "description": "This type is used if the seller is issuing a refund for one or more individual order line items in a multiple line item order. Otherwise, the seller just uses the orderLevelRefundAmount container to specify the amount of the refund for the entire order."
- },
- "ReturnAddress": {
- "type": "object",
- "properties": {
- "addressLine1": {
- "type": "string",
- "description": "The first line of the street address."
- },
- "addressLine2": {
- "type": "string",
- "description": "The second line of the street address. This line is not always necessarily, but is often used for apartment number or suite number, or other relevant information that can not fit on the first line."
- },
- "city": {
- "type": "string",
- "description": "The city of the return address."
- },
- "country": {
- "type": "string",
- "description": "The country's two-letter, ISO 3166-1 country code. See the enumeration type for a country's value. For implementation help, refer to eBay API documentation"
- },
- "county": {
- "type": "string",
- "description": "The county of the return address. Counties are not applicable to all countries."
- },
- "fullName": {
- "type": "string",
- "description": "The full name of return address owner."
- },
- "postalCode": {
- "type": "string",
- "description": "The postal code of the return address."
- },
- "primaryPhone": {
- "description": "This container shows the seller's primary phone number associated with the return address.",
- "$ref": "#/components/schemas/Phone"
- },
- "stateOrProvince": {
- "type": "string",
- "description": "The state or province of the return address."
- }
- },
- "description": "This type is used by the payment dispute methods, and is relevant if the buyer will be returning the item to the seller."
- },
- "SellerActionsToRelease": {
- "type": "object",
- "properties": {
- "sellerActionToRelease": {
- "type": "string",
- "description": "A possible action that the seller can take to expedite the release of a payment hold. A sellerActionToRelease field is returned for each possible action that a seller may take. Possible actions may include providing shipping/tracking information, issuing a refund, providing refund information, contacting customer support, etc."
- }
- },
- "description": "This type is used to state possible action(s) that a seller can take to release a payment hold placed against an order."
- },
- "ShippingFulfillment": {
- "type": "object",
- "properties": {
- "fulfillmentId": {
- "type": "string",
- "description": "The unique identifier of the fulfillment; for example, 9405509699937003457459. This eBay-generated value is created with a successful createShippingFulfillment call."
- },
- "lineItems": {
- "type": "array",
- "description": "This array contains a list of one or more line items (and purchased quantity) to which the fulfillment applies.",
- "items": {
- "$ref": "#/components/schemas/LineItemReference"
- }
- },
- "shipmentTrackingNumber": {
- "type": "string",
- "description": "The tracking number provided by the shipping carrier for the package shipped in this fulfillment. This field is returned if available."
- },
- "shippedDate": {
- "type": "string",
- "description": "The date and time that the fulfillment package was shipped. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field should only be returned if the package has been shipped.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z"
- },
- "shippingCarrierCode": {
- "type": "string",
- "description": "The eBay code identifying the shipping carrier for this fulfillment. This field is returned if available.
Note: The Trading API's ShippingCarrierCodeType enumeration type contains the most current list of eBay shipping carrier codes and the countries served by each carrier. See ShippingCarrierCodeType."
- }
- },
- "description": "This type contains the complete details of an existing fulfillment for an order."
- },
- "ShippingFulfillmentDetails": {
- "type": "object",
- "properties": {
- "lineItems": {
- "type": "array",
- "description": "This array contains a list of or more line items and the quantity that will be shipped in the same package.",
- "items": {
- "$ref": "#/components/schemas/LineItemReference"
- }
- },
- "shippedDate": {
- "type": "string",
- "description": "This is the actual date and time that the fulfillment package was shipped. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. The seller should use the actual date/time that the package was shipped, but if this field is omitted, it will default to the current date/time.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z
Default: The current date and time."
- },
- "shippingCarrierCode": {
- "type": "string",
- "description": "The unique identifier of the shipping carrier being used to ship the line item(s). Technically, the shippingCarrierCode and trackingNumber fields are optional, but generally these fields will be provided if the shipping carrier and tracking number are known.
Note: Use the Trading API's GeteBayDetails call to retrieve the latest shipping carrier enumeration values. When making the GeteBayDetails call, include the DetailName field in the request payload and set its value to ShippingCarrierDetails. Each valid shipping carrier enumeration value is returned in a ShippingCarrierDetails.ShippingCarrier field in the response payload."
- },
- "trackingNumber": {
- "type": "string",
- "description": "The tracking number provided by the shipping carrier for this fulfillment. The seller should be careful that this tracking number is accurate since the buyer will use this tracking number to track shipment, and eBay has no way to verify the accuracy of this number.
This field and the shippingCarrierCode field are mutually dependent. If you include one, you must also include the other.
Note: If you include trackingNumber (and shippingCarrierCode) in the request, the resulting fulfillment's ID (returned in the HTTP location response header) is the tracking number. If you do not include shipment tracking information, the resulting fulfillment ID will default to an arbitrary number such as 999.
Note: Only alphanumeric characters are supported for shipment tracking numbers. Spaces, hyphens, and all other special characters are not supported. Do not include a space in the tracking number even if a space appears in the tracking number on the shipping label."
- }
- },
- "description": "This type contains the details for creating a fulfillment for an order."
- },
- "ShippingFulfillmentPagedCollection": {
- "type": "object",
- "properties": {
- "fulfillments": {
- "type": "array",
- "description": "This array contains one or more fulfillments required for the order that was specified in method endpoint.",
- "items": {
- "$ref": "#/components/schemas/ShippingFulfillment"
- }
- },
- "total": {
- "type": "integer",
- "description": "The total number of fulfillments in the specified order.
Note: If no fulfillments are found for the order, this field is returned with a value of 0.",
- "format": "int32"
- },
- "warnings": {
- "type": "array",
- "description": "This array is only returned if one or more errors or warnings occur with the call request.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type contains the specifications for the entire collection of shipping fulfillments that are associated with the order specified by a getShippingFulfillments call. The fulfillments container returns an array of all the fulfillments in the collection."
- },
- "ShippingStep": {
- "type": "object",
- "properties": {
- "shippingCarrierCode": {
- "type": "string",
- "description": "The unique identifier of the shipping carrier being used to ship the line item.
Note: The Trading API's GeteBayDetails call can be used to retrieve the latest shipping carrier and shipping service option enumeration values."
- },
- "shippingServiceCode": {
- "type": "string",
- "description": "The unique identifier of the shipping service option being used to ship the line item.
Note: Use the Trading API's GeteBayDetails call to retrieve the latest shipping carrier and shipping service option enumeration values. When making the GeteBayDetails call, include the DetailName field in the request payload and set its value to ShippingServiceDetails. Each valid shipping service option (returned in ShippingServiceDetails.ShippingService field) and corresponding shipping carrier (returned in ShippingServiceDetails.ShippingCarrier field) is returned in response payload."
- },
- "shipTo": {
- "description": "This container consists of shipping and contact information about the individual or organization to whom the fulfillment package will be shipped.
Note: When FulfillmentInstructionsType is FULFILLED_BY_EBAY, there will be no shipTo address displayed.
Note: For Digitally Delivered Goods (DDG), this address is the same as the Buyer's Registration Address.
Note: For a Global Shipping Program shipment, this is the address of the international shipping provider's domestic warehouse. The international shipping provider is responsible for delivery to the final destination address. For more information, see Addressing Shipments.",
- "$ref": "#/components/schemas/ExtendedContact"
- },
- "shipToReferenceId": {
- "type": "string",
- "description": "This is the unique identifer of the Global Shipping Program (GSP) shipment. This field is only returned if the line item is being shipped via GSP (the value of the fulfillmentStartInstructions.ebaySupportedFulfillment field will be true. The international shipping provider uses the shipToReferenceId value as the primary reference number to retrieve the relevant details about the buyer, the order, and the fulfillment, so the shipment can be completed.
Sellers must include this value on the shipping label immediately above the street address of the international shipping provider.
Example: \"Reference #1234567890123456\"
Note: This value is the same as the ShipToAddress.ReferenceID value returned by the Trading API's GetOrders call."
- }
- },
- "description": "This type contains shipping information for a fulfillment, including the shipping carrier, the shipping service option, the shipment destination, and the Global Shipping Program reference ID."
- },
- "SimpleAmount": {
- "type": "object",
- "properties": {
- "currency": {
- "type": "string",
- "description": "A three-letter ISO 4217 code (such as USD for US site) that indicates the currency of the amount in the value field. Both the value and currency fields are always returned with the amount container. For implementation help, refer to eBay API documentation"
- },
- "value": {
- "type": "string",
- "description": "The monetary amount of the payment dispute. Both the value and currency fields are always returned with the amount container."
- }
- },
- "description": "This type defines the monetary value of the payment dispute, and the currency used."
- },
- "Tax": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "The monetary amount of the tax. The taxes array is always returned for each line item in the order, but this amount will only be returned when the line item is subject to any type of sales tax. ",
- "$ref": "#/components/schemas/Amount"
- },
- "taxType": {
- "type": "string",
- "description": "Tax type. This field is only available when fieldGroups is set to TAX_BREAKDOWN. If the order has fees, a breakdown of the fees is also provided. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type contains information about any sales tax applied to a line item."
- },
- "TaxAddress": {
- "type": "object",
- "properties": {
- "city": {
- "type": "string",
- "description": "The city name that can be used by sellers for tax purpose."
- },
- "countryCode": {
- "type": "string",
- "description": "The country code that can be used by sellers for tax purpose, represented as a two-letter ISO 3166-1 alpha-2 country code. For example, US represents the United States, and DE represents Germany. For implementation help, refer to eBay API documentation"
- },
- "postalCode": {
- "type": "string",
- "description": "The postal code that can be used by sellers for tax purpose. Usually referred to as Zip codes in the US."
- },
- "stateOrProvince": {
- "type": "string",
- "description": "The state name that can be used by sellers for tax purpose."
- }
- },
- "description": "This container consists of address information that can be used by sellers for tax purpose."
- },
- "TaxIdentifier": {
- "type": "object",
- "properties": {
- "taxpayerId": {
- "type": "string",
- "description": "This value is the unique tax ID associated with the buyer. The type of tax identification is shown in the taxIdentifierType field."
- },
- "taxIdentifierType": {
- "type": "string",
- "description": "This enumeration value indicates the type of tax identification being used for the buyer. The different tax types are defined in the TaxIdentifierTypeEnum type. For implementation help, refer to eBay API documentation"
- },
- "issuingCountry": {
- "type": "string",
- "description": "This two-letter code indicates the country that issued the buyer's tax ID. The country that the two-letter code represents can be found in the CountryCodeEnum type, or in the ISO 3166 standard. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used by the taxIdentifier container that is returned in getOrder. The taxIdentifier container consists of taxpayer identification information for buyers from Italy, Spain, or Guatemala. It is currently only returned for orders occurring on the eBay Italy or eBay Spain marketplaces.
Note: Currently, the taxIdentifier container is only returned in getOrder and not in getOrders. So, if a seller wanted to view a buyer's tax information for a particular order returned in getOrders, that seller would need to use the orderId value for that particular order, and then run a getOrder call against that order ID. "
- },
- "TrackingInfo": {
- "type": "object",
- "properties": {
- "shipmentTrackingNumber": {
- "type": "string",
- "description": "This string value represents the shipment tracking number of the package."
- },
- "shippingCarrierCode": {
- "type": "string",
- "description": "This string value represents the shipping carrier used to ship the package."
- }
- },
- "description": "This type is used for seller provided shipment tracking information."
- },
- "UpdateEvidencePaymentDisputeRequest": {
- "type": "object",
- "properties": {
- "evidenceId": {
- "type": "string",
- "description": "The unique identifier of the evidence set that is being updated with new evidence files.
This ID is returned under the evidence array in the getPaymentDispute response."
- },
- "evidenceType": {
- "type": "string",
- "description": "This field is used to indicate the type of evidence being provided through one or more evidence files. All evidence files (if more than one) should be associated with the evidence type passed in this field.
See the EvidenceTypeEnum type for the supported evidence types. For implementation help, refer to eBay API documentation"
- },
- "files": {
- "type": "array",
- "description": "This array is used to specify one or more evidence files that will be added to the evidence set associated with a payment dispute. At least one evidence file must be specified in the files array.
The unique identifier of an evidence file is returned in the response payload of the uploadEvidence method.",
- "items": {
- "$ref": "#/components/schemas/FileEvidence"
- }
- },
- "lineItems": {
- "type": "array",
- "description": "This required array identifies the order line item(s) for which the evidence file(s) will be applicable.
These values are returned under the evidenceRequests.lineItems array in the getPaymentDispute response.
Note: Both the itemId and lineItemID fields are needed to identify each order line item.",
- "items": {
- "$ref": "#/components/schemas/OrderLineItems"
- }
- }
- },
- "description": "This type is used by the request payload of the updateEvidence method. The updateEvidence method is used to update an existing evidence set against a payment dispute with one or more evidence files."
- }
- },
- "securitySchemes": {
- "api_auth": {
- "type": "oauth2",
- "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
- "flows": {
- "authorizationCode": {
- "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
- "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
- "scopes": {
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment": "View and manage your order fulfillments",
- "https://api.ebay.com/oauth/api_scope/sell.finances": "View and manage your payment and order information to display this information to you and allow you to initiate refunds using the third party application",
- "https://api.ebay.com/oauth/api_scope/sell.payment.dispute": "View and manage disputes and related details (including payment and order information).",
- "https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly": "View your order fulfillments"
}
- }
}
- }
}
- }
}
\ No newline at end of file
diff --git a/specs/sell_inventory_v1_oas3.json b/specs/sell_inventory_v1_oas3.json
index 8f980425..2f819546 100644
--- a/specs/sell_inventory_v1_oas3.json
+++ b/specs/sell_inventory_v1_oas3.json
@@ -1,8522 +1,9823 @@
{
- "openapi": "3.0.0",
- "info": {
- "title": "Inventory API",
- "description": "The Inventory API is used to create and manage inventory, and then to publish and manage this inventory on an eBay marketplace. There are also methods in this API that will convert eligible, active eBay listings into the Inventory API model.",
- "contact": {
- "name": "eBay Inc,"
+ "openapi": "3.0.0",
+ "info": {
+ "title": "Inventory API",
+ "description": "The Inventory API is used to create and manage inventory, and then to publish and manage this inventory on an eBay marketplace. There are also methods in this API that will convert eligible, active eBay listings into the Inventory API model.",
+ "contact": {
+ "name": "eBay Inc,"
+ },
+ "license": {
+ "name": "eBay API License Agreement",
+ "url": "https://developer.ebay.com/join/api-license-agreement"
+ },
+ "version": "1.18.5"
},
- "license": {
- "name": "eBay API License Agreement",
- "url": "https://developer.ebay.com/join/api-license-agreement"
- },
- "version": "1.18.0"
- },
- "servers": [
- {
- "url": "https://api.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/inventory/v1"
- }
- }
- }
- ],
- "paths": {
- "/bulk_create_or_replace_inventory_item": {
- "post": {
- "tags": [
- "inventory_item"
- ],
- "description": "Note: Please note that any eBay listing created using the Inventory API cannot be revised or relisted using the Trading API calls.
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call can be used to create and/or update up to 25 new inventory item records. It is up to sellers whether they want to create a complete inventory item records right from the start, or sellers can provide only some information with the initial bulkCreateOrReplaceInventoryItem call, and then make one or more additional bulkCreateOrReplaceInventoryItem calls to complete all required fields for the inventory item records and prepare for publishing. Upon first creating inventory item records, only the SKU values are required.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Inventory item fields for a list of fields required to publish an offer.
Note: In addition to the authorization header, which is required for all eBay REST API calls, this call also requires the Content-Language and Content-Type headers. See the HTTP request headers section for more information.
In the case of updating existing inventory item records, the bulkCreateOrReplaceInventoryItem call will do a complete replacement of the existing inventory item records, so all fields that are currently defined for the inventory item record are required in that update action, regardless of whether their values changed. So, when replacing/updating an inventory item record, it is advised that the seller run a 'Get' call to retrieve the full details of the inventory item records and see all of its current values/settings before attempting to update the records. Any changes that are made to inventory item records that are part of one or more active eBay listings, a successful call will automatically update these active listings.
The key information that is set with the bulkCreateOrReplaceInventoryItem call include: - Seller-defined SKU value for the product. Each seller product, including products within an item inventory group, must have their own SKU value.
- Condition of the item
- Product details, including any product identifier(s), such as a UPC, ISBN, EAN, or Brand/Manufacturer Part Number pair, a product description, a product title, product/item aspects, and links to images. eBay will use any supplied eBay Product ID (ePID) or a GTIN (UPC, ISBN, or EAN) and attempt to match those identifiers to a product in the eBay Catalog, and if a product match is found, the product details for the inventory item will automatically be populated.
- Quantity of the inventory item that is available for purchase
- Package weight and dimensions, which is required if the seller will be offering calculated shipping options. The package weight will also be required if the seller will be providing flat-rate shipping services, but charging a weight surcharge.
For those who prefer to create or update a single inventory item record, the createOrReplaceInventoryItem method can be used.
",
- "operationId": "bulkCreateOrReplaceInventoryItem",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Language",
- "in": "header",
- "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "Details of the inventories with sku and locale",
- "content": {
- "application/json": {
- "schema": {
- "description": "Details of the inventories with sku and locale",
- "$ref": "#/components/schemas/BulkInventoryItem"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkInventoryItemResponse"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "25096": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This listing is on hold due to a policy violation. You may revise it to resolve the situation. Please check your email for more information."
- },
- "25401": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Invalid listing options removed. {additionalInfo}"
- },
- "25402": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System warning. {additionalInfo}"
- },
- "25504": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "{additionalInfo}"
- },
- "25753": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
- }
- }
- }
- },
- "207": {
- "description": "Multi-Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Any User error. {additionalInfo}"
- },
- "25003": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid price. {additionalInfo}"
- },
- "25004": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid quantity. {additionalInfo}"
- },
- "25005": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid category. {additionalInfo}"
- },
- "25006": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid listing option. {additionalInfo}"
- },
- "25007": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid Shipping policy information. {additionalInfo}"
- },
- "25008": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid Payment policy information. {additionalInfo}"
- },
- "25009": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid Return policy information. {additionalInfo}"
- },
- "25011": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid tax information. {additionalInfo}"
- },
- "25012": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid location. {additionalInfo}"
- },
- "25013": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
- },
- "25014": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid pictures. {additionalInfo}"
- },
- "25015": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid picture URL. {additionalInfo}"
- },
- "25016": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid {fieldName}. {additionalInfo}"
- },
- "25017": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
- },
- "25018": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
- },
- "25019": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
- },
- "25020": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid package details. {additionalInfo}"
- },
- "25021": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid condition information. {additionalInfo}"
- },
- "25022": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25023": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid compatibility information. {additionalInfo}"
- },
- "25026": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Selling limits exceeded. {additionalInfo}"
- },
- "25097": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This listing is on hold due to a policy violation, and revisions are not possible. Please check your email for more information."
- },
- "25098": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{replaceable_value} transaction is not possible as the parent listing is on-hold. Please check your email for further information. "
- },
- "25501": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid picture. {additionalInfo}"
- },
- "25502": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute information. {additionalInfo}"
- },
- "25503": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid product information. {additionalInfo}"
- },
- "25601": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25604": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25701": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "These SKU(s) are not in the system"
- },
- "25702": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "SKU {additionalInfo} is not available in the system"
- },
- "25707": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid sku. sku has to be alphanumeric with upto 50 characters in length"
- },
- "25708": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid sku"
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid request. Invalid value for field {additionalInfo}"
- },
- "25710": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "We didn't find the resource/entity you are requesting. Please verify the request"
- },
- "25713": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This Offer is not available : {additionalInfo}."
- },
- "25715": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid Dimension and Weight"
- },
- "25727": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The number of InventoryItems in the request cannot exceed {additionalInfo}."
- },
- "25728": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "InventoryItems should be unique in the request."
- },
- "25733": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Valid SKU and locale information are required for all the InventoryItems in the request."
- },
- "25759": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "shipToLocationAvailability quantity value should be greater than or equal to auction allocation. Please provide valid quantity or unpublish auction offers of the sku."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Any System error. {additionalInfo}"
- },
- "25025": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Concurrent access of Inventory or InventoryItemGroup. Please try again later"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/bulk_get_inventory_item": {
- "post": {
- "tags": [
- "inventory_item"
- ],
- "description": "This call retrieves up to 25 inventory item records. The SKU value of each inventory item record to retrieve is specified in the request payload.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type header. See the HTTP request headers for more information.
For those who prefer to retrieve only one inventory item record by SKU value, the getInventoryItem method can be used. To retrieve all inventory item records defined on the seller's account, the getInventoryItems method can be used (with pagination control if desired).",
- "operationId": "bulkGetInventoryItem",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "Details of the inventories with sku and locale",
- "content": {
- "application/json": {
- "schema": {
- "description": "Details of the inventories with sku and locale",
- "$ref": "#/components/schemas/BulkGetInventoryItem"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkGetInventoryItemResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi-Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25702": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "SKU {additionalInfo} is not available in the system"
- },
- "25708": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid SKU."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid request. Invalid value for field {additionalInfo}"
- },
- "25710": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "We didn't find the resource/entity you are requesting. Please verify the request"
- },
- "25727": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The number of InventoryItems in the request cannot exceed {additionalInfo}."
- },
- "25734": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "SKU should be unique in the request."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Any System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/bulk_update_price_quantity": {
- "post": {
- "tags": [
- "inventory_item"
- ],
- "description": "This call is used by the seller to update the total ship-to-home quantity of one inventory item, and/or to update the price and/or quantity of one or more offers associated with one inventory item. Up to 25 offers associated with an inventory item may be updated with one bulkUpdatePriceQuantity call. Only one SKU (one product) can be updated per call.
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type header. See the HTTP request headers for more information.
The getOffers call can be used to retrieve all offers associated with a SKU. The seller will just pass in the correct SKU value through the sku query parameter. To update an offer, the offerId value is required, and this value is returned in the getOffers call response. It is also useful to know which offers are unpublished and which ones are published. To get this status, look for the status value in the getOffers call response. Offers in the published state are live eBay listings, and these listings will be revised with a successful bulkUpdatePriceQuantity call.
An issue will occur if duplicate offerId values are passed through the same offers container, or if one or more of the specified offers are associated with different products/SKUs.
Note: For multiple-variation listings, it is recommended that the bulkUpdatePriceQuantity call be used to update price and quantity information for each SKU within that multiple-variation listing instead of using createOrReplaceInventoryItem calls to update the price and quantity for each SKU. Just remember that only one SKU (one product variation) can be updated per call.",
- "operationId": "bulkUpdatePriceQuantity",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "Price and allocation details for the given SKU and Marketplace",
- "content": {
- "application/json": {
- "schema": {
- "description": "Price and allocation details for the given SKU and Marketplace",
- "$ref": "#/components/schemas/BulkPriceQuantity"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkPriceQuantityResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi-Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Any User error. {additionalInfo}"
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}. {additionalInfo}"
- },
- "25759": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "shipToLocationAvailability quantity value should be greater than or equal to auction allocation. Please provide valid quantity or unpublish auction offers of the sku."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/inventory_item/{sku}": {
- "get": {
- "tags": [
- "inventory_item"
- ],
- "description": "This call retrieves the inventory item record for a given SKU. The SKU value is passed in at the end of the call URI. There is no request payload for this call.
The authorization header is the only required HTTP header for this call, and it is required for all Inventory API calls. See the HTTP request headers section for more information.
For those who prefer to retrieve numerous inventory item records by SKU value with one call (up to 25 at a time), the bulkGetInventoryItem method can be used. To retrieve all inventory item records defined on the seller's account, the getInventoryItems method can be used (with pagination control if desired).",
- "operationId": "getInventoryItem",
- "parameters": [
- {
- "name": "sku",
- "in": "path",
- "description": "This path parameter specifies the seller-defined SKU value of the product whose inventory item record you wish to retrieve.
Use the getInventoryItems method to retrieve SKU values.
Max length: 50",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/InventoryItemWithSkuLocaleGroupid"
+ "servers": [
+ {
+ "url": "https://api.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/inventory/v1"
}
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25702": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{skuValue} could not be found or is not available in the system."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}"
- },
- "25710": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "We didn't find the resource/entity you are requesting. Please verify the request"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "put": {
- "tags": [
- "inventory_item"
- ],
- "description": "Note: Please note that any eBay listing created using the Inventory API cannot be revised or relisted using the Trading API calls.
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call creates a new inventory item record or replaces an existing inventory item record. It is up to sellers whether they want to create a complete inventory item record right from the start, or sellers can provide only some information with the initial createOrReplaceInventoryItem call, and then make one or more additional createOrReplaceInventoryItem calls to complete all required fields for the inventory item record and prepare it for publishing. Upon first creating an inventory item record, only the SKU value in the call path is required.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Inventory item fields for a list of fields required to publish an offer.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.
In the case of replacing an existing inventory item record, the createOrReplaceInventoryItem call will do a complete replacement of the existing inventory item record, so all fields that are currently defined for the inventory item record are required in that update action, regardless of whether their values changed. So, when replacing/updating an inventory item record, it is advised that the seller run a getInventoryItem call to retrieve the full inventory item record and see all of its current values/settings before attempting to update the record. And if changes are made to an inventory item that is part of one or more active eBay listings, a successful call will automatically update these eBay listings.
The key information that is set with the createOrReplaceInventoryItem call include: - Seller-defined SKU value for the product. Each seller product, including products within an item inventory group, must have their own SKU value. This SKU value is passed in at the end of the call URI
- Condition of the item
- Product details, including any product identifier(s), such as a UPC, ISBN, EAN, or Brand/Manufacturer Part Number pair, a product description, a product title, product/item aspects, and links to images. eBay will use any supplied eBay Product ID (ePID) or a GTIN (UPC, ISBN, or EAN) and attempt to match those identifiers to a product in the eBay Catalog, and if a product match is found, the product details for the inventory item will automatically be populated.
- Quantity of the inventory item that is available for purchase
- Package weight and dimensions, which is required if the seller will be offering calculated shipping options. The package weight will also be required if the seller will be providing flat-rate shipping services, but charging a weight surcharge.
In addition to the authorization header, which is required for all eBay REST API calls, the createOrReplaceInventoryItem call also requires the Content-Language header, that sets the natural language that will be used in the field values of the request payload. For US English, the code value passed in this header should be en-US. To view other supported Content-Language values, and to read more about all supported HTTP headers for eBay REST API calls, see the HTTP request headers topic in the Using eBay RESTful APIs document.
For those who prefer to create or update numerous inventory item records with one call (up to 25 at a time), the bulkCreateOrReplaceInventoryItem method can be used.
",
- "operationId": "createOrReplaceInventoryItem",
- "parameters": [
- {
- "name": "Content-Language",
- "in": "header",
- "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "sku",
- "in": "path",
- "description": "This path parameter specifies the seller-defined SKU value for the inventory item being created or updated. SKU values must be unique across the seller's inventory.
Max length: 50",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
}
- }
- ],
- "requestBody": {
- "description": "Details of the inventory item record.",
- "content": {
- "application/json": {
- "schema": {
- "description": "Details of the inventory item record.",
- "$ref": "#/components/schemas/InventoryItem"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "headers": {
- "Content-Language": {
- "schema": {
- "type": "string",
- "description": "This header controls the language that is used for any returned errors or warnings in the call response."
- }
- }
+ }
+ ],
+ "paths": {
+ "/bulk_create_or_replace_inventory_item": {
+ "post": {
+ "tags": [
+ "inventory_item"
+ ],
+ "description": "Note: Please note that any eBay listing created using the Inventory API cannot be revised or relisted using the Trading API calls.
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call can be used to create and/or update up to 25 new inventory item records. It is up to sellers whether they want to create a complete inventory item records right from the start, or sellers can provide only some information with the initial bulkCreateOrReplaceInventoryItem call, and then make one or more additional bulkCreateOrReplaceInventoryItem calls to complete all required fields for the inventory item records and prepare for publishing. Upon first creating inventory item records, only the SKU values are required.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Inventory item fields for a list of fields required to publish an offer.
Note: In addition to the authorization header, which is required for all eBay REST API calls, this call also requires the Content-Language and Content-Type headers. See the HTTP request headers section for more information.
In the case of updating existing inventory item records, the bulkCreateOrReplaceInventoryItem call will do a complete replacement of the existing inventory item records, so all fields that are currently defined for the inventory item record are required in that update action, regardless of whether their values changed. So, when replacing/updating an inventory item record, it is advised that the seller run a 'Get' call to retrieve the full details of the inventory item records and see all of its current values/settings before attempting to update the records. Any changes that are made to inventory item records that are part of one or more active eBay listings, a successful call will automatically update these active listings.
The key information that is set with the bulkCreateOrReplaceInventoryItem call include: - Seller-defined SKU value for the product. Each seller product, including products within an item inventory group, must have their own SKU value.
- Condition of the item
- Product details, including any product identifier(s), such as a UPC, ISBN, EAN, or Brand/Manufacturer Part Number pair, a product description, a product title, product/item aspects, and links to images. eBay will use any supplied eBay Product ID (ePID) or a GTIN (UPC, ISBN, or EAN) and attempt to match those identifiers to a product in the eBay Catalog, and if a product match is found, the product details for the inventory item will automatically be populated.
- Quantity of the inventory item that is available for purchase
- Package weight and dimensions, which is required if the seller will be offering calculated shipping options. The package weight will also be required if the seller will be providing flat-rate shipping services, but charging a weight surcharge.
For those who prefer to create or update a single inventory item record, the createOrReplaceInventoryItem method can be used.
",
+ "operationId": "bulkCreateOrReplaceInventoryItem",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Language",
+ "in": "header",
+ "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Details of the inventories with sku and locale",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Details of the inventories with sku and locale",
+ "$ref": "#/components/schemas/BulkInventoryItem"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkInventoryItemResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25096": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This listing is on hold due to a policy violation. You may revise it to resolve the situation. Please check your email for more information."
+ },
+ "25124": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing requires a minimum 30-day return period and seller-paid return shipping. eBay automatically updated the listing's return policy settings to meet these requirements. Sellers using business policies should update their return business policy for future P&A listings. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25126": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Certification, Certification Number, Circulated/Uncirculated and Grade aspects will be deprecated in the near future. Please use the new condition grading conditions and descriptors."
+ },
+ "25401": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Invalid listing options removed. {additionalInfo}"
+ },
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System warning. {additionalInfo}"
+ },
+ "25504": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "{additionalInfo}"
+ },
+ "25753": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi-Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Any User error. {additionalInfo}"
+ },
+ "25003": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid price. {additionalInfo}"
+ },
+ "25004": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid quantity. {additionalInfo}"
+ },
+ "25005": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid category. {additionalInfo}"
+ },
+ "25006": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid listing option. {additionalInfo}"
+ },
+ "25007": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid Shipping policy information. {additionalInfo}"
+ },
+ "25008": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid Payment policy information. {additionalInfo}"
+ },
+ "25009": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid Return policy information. {additionalInfo}"
+ },
+ "25011": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid tax information. {additionalInfo}"
+ },
+ "25012": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid location. {additionalInfo}"
+ },
+ "25013": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
+ },
+ "25014": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid pictures. {additionalInfo}"
+ },
+ "25015": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid picture URL. {additionalInfo}"
+ },
+ "25016": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid {fieldName}. {additionalInfo}"
+ },
+ "25017": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
+ },
+ "25018": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
+ },
+ "25019": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
+ },
+ "25020": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid package details. {additionalInfo}"
+ },
+ "25021": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid condition information. {additionalInfo}"
+ },
+ "25022": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25023": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid compatibility information. {additionalInfo}"
+ },
+ "25026": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Selling limits exceeded. {additionalInfo}"
+ },
+ "25097": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This listing is on hold due to a policy violation, and revisions are not possible. Please check your email for more information."
+ },
+ "25098": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{replaceable_value} transaction is not possible as the parent listing is on-hold. Please check your email for further information. "
+ },
+ "25123": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing has a non-compliant domestic return policy. Please update the return window to 30-days (or more) and/or update return shipping cost payer to Seller, and then make another call. Sellers using business policies must make the same changes to their return business policy and then make another call. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25501": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid picture. {additionalInfo}"
+ },
+ "25502": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute information. {additionalInfo}"
+ },
+ "25503": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid product information. {additionalInfo}"
+ },
+ "25601": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25604": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25701": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "These SKU(s) are not in the system"
+ },
+ "25702": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "SKU {additionalInfo} is not available in the system"
+ },
+ "25707": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid sku. sku has to be alphanumeric with upto 50 characters in length"
+ },
+ "25708": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid sku"
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid request. Invalid value for field {additionalInfo}"
+ },
+ "25710": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "We didn't find the resource/entity you are requesting. Please verify the request"
+ },
+ "25713": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This Offer is not available : {additionalInfo}."
+ },
+ "25715": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid Dimension and Weight"
+ },
+ "25727": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The number of InventoryItems in the request cannot exceed {additionalInfo}."
+ },
+ "25728": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "InventoryItems should be unique in the request."
+ },
+ "25733": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Valid SKU and locale information are required for all the InventoryItems in the request."
+ },
+ "25759": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "shipToLocationAvailability quantity value should be greater than or equal to auction allocation. Please provide valid quantity or unpublish auction offers of the sku."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Any System error. {additionalInfo}"
+ },
+ "25025": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Concurrent access of Inventory or InventoryItemGroup. Please try again later"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/bulk_get_inventory_item": {
+ "post": {
+ "tags": [
+ "inventory_item"
+ ],
+ "description": "This call retrieves up to 25 inventory item records. The SKU value of each inventory item record to retrieve is specified in the request payload.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type header. See the HTTP request headers for more information.
For those who prefer to retrieve only one inventory item record by SKU value, the getInventoryItem method can be used. To retrieve all inventory item records defined on the seller's account, the getInventoryItems method can be used (with pagination control if desired).",
+ "operationId": "bulkGetInventoryItem",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Details of the inventories with sku and locale",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Details of the inventories with sku and locale",
+ "$ref": "#/components/schemas/BulkGetInventoryItem"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkGetInventoryItemResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi-Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25702": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "SKU {additionalInfo} is not available in the system"
+ },
+ "25708": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid SKU."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid request. Invalid value for field {additionalInfo}"
+ },
+ "25710": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "We didn't find the resource/entity you are requesting. Please verify the request"
+ },
+ "25727": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The number of InventoryItems in the request cannot exceed {additionalInfo}."
+ },
+ "25734": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "SKU should be unique in the request."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Any System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/bulk_update_price_quantity": {
+ "post": {
+ "tags": [
+ "inventory_item"
+ ],
+ "description": "This call is used by the seller to update the total ship-to-home quantity of one inventory item, and/or to update the price and/or quantity of one or more offers associated with one inventory item. Up to 25 offers associated with an inventory item may be updated with one bulkUpdatePriceQuantity call. Only one SKU (one product) can be updated per call.
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type header. See the HTTP request headers for more information.
The getOffers call can be used to retrieve all offers associated with a SKU. The seller will just pass in the correct SKU value through the sku query parameter. To update an offer, the offerId value is required, and this value is returned in the getOffers call response. It is also useful to know which offers are unpublished and which ones are published. To get this status, look for the status value in the getOffers call response. Offers in the published state are live eBay listings, and these listings will be revised with a successful bulkUpdatePriceQuantity call.
An issue will occur if duplicate offerId values are passed through the same offers container, or if one or more of the specified offers are associated with different products/SKUs.
Note: For multiple-variation listings, it is recommended that the bulkUpdatePriceQuantity call be used to update price and quantity information for each SKU within that multiple-variation listing instead of using createOrReplaceInventoryItem calls to update the price and quantity for each SKU. Just remember that only one SKU (one product variation) can be updated per call.",
+ "operationId": "bulkUpdatePriceQuantity",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Price and allocation details for the given SKU and Marketplace",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Price and allocation details for the given SKU and Marketplace",
+ "$ref": "#/components/schemas/BulkPriceQuantity"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkPriceQuantityResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi-Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Any User error. {additionalInfo}"
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}. {additionalInfo}"
+ },
+ "25759": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "shipToLocationAvailability quantity value should be greater than or equal to auction allocation. Please provide valid quantity or unpublish auction offers of the sku."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/inventory_item/{sku}": {
+ "get": {
+ "tags": [
+ "inventory_item"
+ ],
+ "description": "This call retrieves the inventory item record for a given SKU. The SKU value is passed in at the end of the call URI. There is no request payload for this call.
The authorization header is the only required HTTP header for this call, and it is required for all Inventory API calls. See the HTTP request headers section for more information.
For those who prefer to retrieve numerous inventory item records by SKU value with one call (up to 25 at a time), the bulkGetInventoryItem method can be used. To retrieve all inventory item records defined on the seller's account, the getInventoryItems method can be used (with pagination control if desired).",
+ "operationId": "getInventoryItem",
+ "parameters": [
+ {
+ "name": "sku",
+ "in": "path",
+ "description": "This path parameter specifies the seller-defined SKU value of the product whose inventory item record you wish to retrieve.
Use the getInventoryItems method to retrieve SKU values.
Max length: 50",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/InventoryItemWithSkuLocaleGroupid"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25702": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{skuValue} could not be found or is not available in the system."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}"
+ },
+ "25710": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "We didn't find the resource/entity you are requesting. Please verify the request"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BaseResponse"
- }
- }
+ "put": {
+ "tags": [
+ "inventory_item"
+ ],
+ "description": "Note: Please note that any eBay listing created using the Inventory API cannot be revised or relisted using the Trading API calls.
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call creates a new inventory item record or replaces an existing inventory item record. It is up to sellers whether they want to create a complete inventory item record right from the start, or sellers can provide only some information with the initial createOrReplaceInventoryItem call, and then make one or more additional createOrReplaceInventoryItem calls to complete all required fields for the inventory item record and prepare it for publishing. Upon first creating an inventory item record, only the SKU value in the call path is required.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Inventory item fields for a list of fields required to publish an offer.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.
In the case of replacing an existing inventory item record, the createOrReplaceInventoryItem call will do a complete replacement of the existing inventory item record, so all fields that are currently defined for the inventory item record are required in that update action, regardless of whether their values changed. So, when replacing/updating an inventory item record, it is advised that the seller run a getInventoryItem call to retrieve the full inventory item record and see all of its current values/settings before attempting to update the record. And if changes are made to an inventory item that is part of one or more active eBay listings, a successful call will automatically update these eBay listings.
The key information that is set with the createOrReplaceInventoryItem call include: - Seller-defined SKU value for the product. Each seller product, including products within an item inventory group, must have their own SKU value. This SKU value is passed in at the end of the call URI
- Condition of the item
- Product details, including any product identifier(s), such as a UPC, ISBN, EAN, or Brand/Manufacturer Part Number pair, a product description, a product title, product/item aspects, and links to images. eBay will use any supplied eBay Product ID (ePID) or a GTIN (UPC, ISBN, or EAN) and attempt to match those identifiers to a product in the eBay Catalog, and if a product match is found, the product details for the inventory item will automatically be populated.
- Quantity of the inventory item that is available for purchase
- Package weight and dimensions, which is required if the seller will be offering calculated shipping options. The package weight will also be required if the seller will be providing flat-rate shipping services, but charging a weight surcharge.
In addition to the authorization header, which is required for all eBay REST API calls, the createOrReplaceInventoryItem call also requires the Content-Language header, that sets the natural language that will be used in the field values of the request payload. For US English, the code value passed in this header should be en-US. To view other supported Content-Language values, and to read more about all supported HTTP headers for eBay REST API calls, see the HTTP request headers topic in the Using eBay RESTful APIs document.
For those who prefer to create or update numerous inventory item records with one call (up to 25 at a time), the bulkCreateOrReplaceInventoryItem method can be used.
",
+ "operationId": "createOrReplaceInventoryItem",
+ "parameters": [
+ {
+ "name": "Content-Language",
+ "in": "header",
+ "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sku",
+ "in": "path",
+ "description": "This path parameter specifies the seller-defined SKU value for the inventory item being created or updated. SKU values must be unique across the seller's inventory.
Max length: 50",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Details of the inventory item record.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Details of the inventory item record.",
+ "$ref": "#/components/schemas/InventoryItem"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "headers": {
+ "Content-Language": {
+ "schema": {
+ "type": "string",
+ "description": "This header controls the language that is used for any returned errors or warnings in the call response."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BaseResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25096": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This listing is on hold due to a policy violation. You may revise it to resolve the situation. Please check your email for more information."
+ },
+ "25124": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing requires a minimum 30-day return period and seller-paid return shipping. eBay automatically updated the listing's return policy settings to meet these requirements. Sellers using business policies should update their return business policy for future P&A listings. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25126": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Certification, Certification Number, Circulated/Uncirculated and Grade aspects will be deprecated in the near future. Please use the new condition grading conditions and descriptors."
+ },
+ "25401": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Invalid listing format removed. {additionalInfo}"
+ },
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System warning. {additionalInfo}"
+ },
+ "25504": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "service\t{additionalInfo}"
+ },
+ "25753": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
+ }
+ }
+ }
+ },
+ "201": {
+ "description": "Created",
+ "headers": {
+ "Content-Language": {
+ "schema": {
+ "type": "string",
+ "description": "This header controls the language that is used for any returned errors or warnings in the call response."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BaseResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25096": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This listing is on hold due to a policy violation. You may revise it to resolve the situation. Please check your email for more information."
+ },
+ "25124": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing requires a minimum 30-day return period and seller-paid return shipping. eBay automatically updated the listing's return policy settings to meet these requirements. Sellers using business policies should update their return business policy for future P&A listings. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25126": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Certification, Certification Number, Circulated/Uncirculated and Grade aspects will be deprecated in the near future. Please use the new condition grading conditions and descriptors."
+ },
+ "25401": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Invalid listing format removed. {additionalInfo}"
+ },
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System warning. {additionalInfo}"
+ },
+ "25504": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "service\t{additionalInfo}"
+ },
+ "25753": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "A user error has occurred. {additionalInfo}"
+ },
+ "25003": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}"
+ },
+ "25004": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}"
+ },
+ "25005": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}"
+ },
+ "25006": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}"
+ },
+ "25007": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}"
+ },
+ "25008": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}"
+ },
+ "25009": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}"
+ },
+ "25011": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}"
+ },
+ "25012": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid inventory location. {additionalInfo}"
+ },
+ "25013": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
+ },
+ "25014": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}"
+ },
+ "25015": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}"
+ },
+ "25016": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The {fieldName} value is invalid. {additionalInfo}"
+ },
+ "25017": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
+ },
+ "25018": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
+ },
+ "25019": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
+ },
+ "25020": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}"
+ },
+ "25021": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}"
+ },
+ "25022": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25023": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid compatibility information. {additionalInfo}"
+ },
+ "25026": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Selling limit exceeded. {additionalInfo}"
+ },
+ "25029": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is required for this category."
+ },
+ "25031": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not valid and needs to be a number between {min} and {max}"
+ },
+ "25034": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Only {max value} policies can be specified"
+ },
+ "25035": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The specified policy is not found for the market place"
+ },
+ "25036": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The policy(ies) {PolicyId} is not of type {PolicyEnum}"
+ },
+ "25038": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer or is ending within 12 hours"
+ },
+ "25039": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
+ },
+ "25040": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
+ },
+ "25041": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s)."
+ },
+ "25042": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, free shipping must be provided."
+ },
+ "25043": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, returns must be accepted."
+ },
+ "25044": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, refund must be provided as Money Back."
+ },
+ "25045": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days."
+ },
+ "25046": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, seller must pay the cost for return shipping."
+ },
+ "25047": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition"
+ },
+ "25048": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition in this Category"
+ },
+ "25049": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition for the selected Brand"
+ },
+ "25050": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title."
+ },
+ "25051": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle"
+ },
+ "25052": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, at least {replaceable_value} images must be provided"
+ },
+ "25076": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{replaceable_value} ID(s) {replaceable_value} not found. Please use valid ID(s)."
+ },
+ "25077": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Duplicate Regulatory ID(s) {replaceable_value} sent in the request. Duplicate ID(s) have been ignored."
+ },
+ "25078": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Hazmat structure incorrect for {replaceable_value}."
+ },
+ "25079": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Repair score invalid. Repair score must be in the range from {replaceable_value} to {replaceable_value} with one decimal place."
+ },
+ "25080": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The value of the {0} field is invalid. Field must not exceed {replaceable_value} characters."
+ },
+ "25081": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Hazardous material information incomplete. Your listing must include hazardous statements."
+ },
+ "25083": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Energy efficiency image is missing. Image is required with image description."
+ },
+ "25084": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The listing must have both an energy efficiency label and a product information sheet."
+ },
+ "25086": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The URL provided must be an eBay Picture Service URL."
+ },
+ "25088": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The email address provided is formatted incorrectly."
+ },
+ "25089": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} global compliance policies allowed. Excess policies ignored."
+ },
+ "25090": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} compliance policies per region allowed. Excess policies ignored."
+ },
+ "25091": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than a total of {replaceable_value} compliance policies allowed. Excess policies ignored."
+ },
+ "25092": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} global takeback policy allowed."
+ },
+ "25093": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} takeback policy per region allowed. Excess policies ignored."
+ },
+ "25094": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than a total of {replaceable_value} takeback policies allowed."
+ },
+ "25095": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Region invalid for regional custom policy. Regions allowed are {replaceable_value}."
+ },
+ "25097": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This listing is on hold due to a policy violation, and revisions are not possible. Please check your email for more information."
+ },
+ "25098": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{replaceable_value} transaction is not possible as the parent listing is on-hold. Please check your email for further information."
+ },
+ "25104": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Regulatory document ID(s) {replaceable_value} not found. Please use valid ID(s)."
+ },
+ "25106": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Regulatory document structure incorrect. Max allowed number of entries is {replaceable_value}."
+ },
+ "25107": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid document state for ID(s) {replaceable_value}. Documents must be in the SUBMITTED or ACCEPTED state."
+ },
+ "25108": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Product Safety structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
+ },
+ "25109": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Product safety information incomplete. Your listing must include pictograms or safety statements."
+ },
+ "25110": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Manufacturer address information is incomplete. When providing the address, please provide the street, city, postal code and country"
+ },
+ "25111": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Manufacturer information is incomplete. Please provide the company name."
+ },
+ "25112": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
+ },
+ "25113": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person address information is incomplete. When providing the address, please provide the street, city, postal code and country"
+ },
+ "25114": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person information is incomplete. Please provide the company name."
+ },
+ "25115": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Either the Manufacturer or at least one of the Responsible Persons must be located in the EU."
+ },
+ "25116": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Please provide a minimum of {replaceable_value} and a maximum of {replaceable_value} types for a Responsible Person."
+ },
+ "25118": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller must provide at least one form of contact info for Manufacturer - either address, email, contact URL or phone."
+ },
+ "25119": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller must provide at least one form of contact info for Responsible Person - either address, email, contact URL or phone."
+ },
+ "25120": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing in {categoryName}, key information such as {fieldName} comes from eBayās catalog and should be left blank."
+ },
+ "25121": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing in {categoryName}, sellers are required to adopt eBayās catalog data which will provide all the necessary details for the product."
+ },
+ "25122": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The contact URL is incorrectly formatted. Please update the formatting."
+ },
+ "25123": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing has a non-compliant domestic return policy. Please update the return window to 30-days (or more) and/or update return shipping cost payer to Seller, and then make another call. Sellers using business policies must make the same changes to their return business policy and then make another call. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25501": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture. {additionalInfo}"
+ },
+ "25502": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute information. {additionalInfo}"
+ },
+ "25503": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid product information. {additionalInfo}"
+ },
+ "25601": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{fieldName} is an invalid attribute. "
+ },
+ "25604": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25701": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "One or more of the supplied SKU(s) could not be found in the system."
+ },
+ "25702": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{skuValue} could not be found or is not available in the system."
+ },
+ "25707": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This is an invalid value for a SKU. Only alphanumeric characters can be used for SKUs, and their length must not exceed 50 characters."
+ },
+ "25708": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid SKU."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}"
+ },
+ "25710": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "We didn't find the resource/entity you are requesting. Please verify the request."
+ },
+ "25713": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This Offer is not available : {additionalInfo}."
+ },
+ "25715": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid values for dimensions and/or weight of shipping package."
+ },
+ "25752": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate provided is invalid."
+ },
+ "25759": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{replaceable_value} transaction is not possible as the parent listing is on-hold. Please check your email for further information. "
+ },
+ "25760": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "shipToLocationAvailability quantity insufficient to create auction listings."
+ },
+ "25766": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The takeBackPolicyId field must be a long value type. Please correct the error."
+ },
+ "25767": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The productCompliancePolicyId field must be a long value type. Please correct the error."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ },
+ "25025": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "x-response-codes": {
- "errors": {
- "25096": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This listing is on hold due to a policy violation. You may revise it to resolve the situation. Please check your email for more information."
- },
- "25401": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Invalid listing format removed. {additionalInfo}"
- },
- "25402": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System warning. {additionalInfo}"
- },
- "25504": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "service\t{additionalInfo}"
- },
- "25753": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
- }
- }
- }
- },
- "201": {
- "description": "Created",
- "headers": {
- "Content-Language": {
- "schema": {
- "type": "string",
- "description": "This header controls the language that is used for any returned errors or warnings in the call response."
- }
- }
+ "delete": {
+ "tags": [
+ "inventory_item"
+ ],
+ "description": "This call is used to delete an inventory item record associated with a specified SKU. A successful call will not only delete that inventory item record, but will also have the following effects:- Delete any and all unpublished offers associated with that SKU;
- Delete any and all single-variation eBay listings associated with that SKU;
- Automatically remove that SKU from a multiple-variation listing and remove that SKU from any and all inventory item groups in which that SKU was a member.
The authorization header is the only required HTTP header for this call. See the HTTP request headers section for more information.
",
+ "operationId": "deleteInventoryItem",
+ "parameters": [
+ {
+ "name": "sku",
+ "in": "path",
+ "description": "This path parameter specifies the seller-defined SKU value of the product whose inventory item record you wish to delete.
Use the getInventoryItems method to retrieve SKU values.
Max length: 50",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25702": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{skuValue} could not be found or is not available in the system."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}. {additionalInfo}"
+ },
+ "25710": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "We didn't find the resource/entity you are requesting. Please verify the request"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/inventory_item": {
+ "get": {
+ "tags": [
+ "inventory_item"
+ ],
+ "description": "This call retrieves all inventory item records defined for the seller's account. The limit query parameter allows the seller to control how many records are returned per page, and the offset query parameter is used to retrieve a specific page of records. The seller can make multiple calls to scan through multiple pages of records. There is no request payload for this call.
The authorization header is the only required HTTP header for this call, and it is required for all Inventory API calls. See the HTTP request headers section for more information.
For those who prefer to retrieve numerous inventory item records by SKU value with one call (up to 25 at a time), the bulkGetInventoryItem method can be used.",
+ "operationId": "getInventoryItems",
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The value passed in this query parameter sets the maximum number of records to return per page of data. Although this field is a string, the value passed in this field should be an integer from 1 to 200.
Min: 1
Max: 200
Default: 25",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "The value passed in this query parameter sets the page number to retrieve. The first page of records has a value of 0, the second page of records has a value of 1, and so on. If this query parameter is not set, its value defaults to 0, and the first page of records is returned. ",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/InventoryItems"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25706": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "You have provided invalid pagination values. {additionalInfo}."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}."
+ },
+ "25710": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "We didn't find the resource/entity you are requesting. Please verify the request"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/inventory_item/{sku}/product_compatibility": {
+ "get": {
+ "tags": [
+ "product_compatibility"
+ ],
+ "description": "This call is used by the seller to retrieve the list of products that are compatible with the inventory item. The SKU value for the inventory item is passed into the call URI, and a successful call with return the compatible vehicle list associated with this inventory item. Product compatibility is currently only applicable to motor vehicle parts and accessory categories, but more categories may be supported in the future.",
+ "operationId": "getProductCompatibility",
+ "parameters": [
+ {
+ "name": "sku",
+ "in": "path",
+ "description": "This path parameter specifies the SKU (stock keeping unit) of the inventory item associated with the product compatibility list being retrieved.
Use the getInventoryItems method to retrieve SKU values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Compatibility"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25702": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{skuValue} could not be found or is not available in the system."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}. {additionalInfo}"
+ },
+ "25710": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "We didn't find the resource/entity you are requesting. Please verify the request"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BaseResponse"
- }
- }
+ "put": {
+ "tags": [
+ "product_compatibility"
+ ],
+ "description": "This call is used by the seller to create or replace a list of products that are compatible with the inventory item. The inventory item is identified with a SKU value in the URI. Product compatibility is currently only applicable to motor vehicle parts and accessory categories, but more categories may be supported in the future.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.",
+ "operationId": "createOrReplaceProductCompatibility",
+ "parameters": [
+ {
+ "name": "Content-Language",
+ "in": "header",
+ "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sku",
+ "in": "path",
+ "description": "This path parameter specifies the SKU (stock keeping unit) of the inventory item associated with the compatibility list being created.
Use the getInventoryItems method to retrieve SKU values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Details of the compatibility",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Details of the compatibility",
+ "$ref": "#/components/schemas/Compatibility"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "headers": {
+ "Content-Language": {
+ "schema": {
+ "type": "string",
+ "description": "This response header sets the natural language that will be provided in the field values of the response payload."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BaseResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25124": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing requires a minimum 30-day return period and seller-paid return shipping. eBay automatically updated the listing's return policy settings to meet these requirements. Sellers using business policies should update their return business policy for future P&A listings. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25401": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Invalid listing format removed. {additionalInfo}"
+ },
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System warning. {additionalInfo}"
+ }
+ }
+ }
+ },
+ "201": {
+ "description": "Created",
+ "headers": {
+ "Content-Language": {
+ "schema": {
+ "type": "string",
+ "description": "This response header sets the natural language that will be provided in the field values of the response payload."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BaseResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25124": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing requires a minimum 30-day return period and seller-paid return shipping. eBay automatically updated the listing's return policy settings to meet these requirements. Sellers using business policies should update their return business policy for future P&A listings. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25401": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Invalid listing format removed. {additionalInfo}"
+ },
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System warning. {additionalInfo}"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "A user error has occurred. {additionalInfo}"
+ },
+ "25003": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}"
+ },
+ "25004": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}"
+ },
+ "25005": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}"
+ },
+ "25006": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}"
+ },
+ "25007": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}"
+ },
+ "25008": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}"
+ },
+ "25009": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}"
+ },
+ "25011": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}"
+ },
+ "25012": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid inventory location. {additionalInfo}"
+ },
+ "25013": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
+ },
+ "25014": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}"
+ },
+ "25015": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}"
+ },
+ "25016": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The {fieldName} value is invalid. {additionalInfo}"
+ },
+ "25017": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
+ },
+ "25018": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
+ },
+ "25019": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
+ },
+ "25020": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}"
+ },
+ "25021": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}"
+ },
+ "25022": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25023": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid compatibility information. {additionalInfo}"
+ },
+ "25026": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Selling limit exceeded. {additionalInfo}"
+ },
+ "25123": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing has a non-compliant domestic return policy. Please update the return window to 30-days (or more) and/or update return shipping cost payer to Seller, and then make another call. Sellers using business policies must make the same changes to their return business policy and then make another call. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25702": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{skuValue} could not be found or is not available in the system."
+ },
+ "25739": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "User input error. The number of compatibilityProperties in the request cannot exceed {additionalInfo}."
+ },
+ "25740": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "User input error. Invalid name for compatibilityProperties. The length should be between 1 and {additionalInfo} characters."
+ },
+ "25741": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "User input error. Invalid value for compatibilityProperties. The length should be between 1 and {additionalInfo} characters."
+ },
+ "25742": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "User input error. productFamilyProperties and compatibilityProperties cannot be used together. Please use compatibilityProperties."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ },
+ "25025": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "x-response-codes": {
- "errors": {
- "25096": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This listing is on hold due to a policy violation. You may revise it to resolve the situation. Please check your email for more information."
- },
- "25401": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Invalid listing format removed. {additionalInfo}"
- },
- "25402": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System warning. {additionalInfo}"
- },
- "25504": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "service\t{additionalInfo}"
- },
- "25753": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
- }
- }
- }
- },
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "A user error has occurred. {additionalInfo}"
- },
- "25003": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}"
- },
- "25004": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}"
- },
- "25005": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}"
- },
- "25006": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}"
- },
- "25007": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}"
- },
- "25008": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}"
- },
- "25009": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}"
- },
- "25011": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}"
- },
- "25012": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid inventory location. {additionalInfo}"
- },
- "25013": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
- },
- "25014": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}"
- },
- "25015": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}"
- },
- "25016": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The {fieldName} value is invalid. {additionalInfo}"
- },
- "25017": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
- },
- "25018": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
- },
- "25019": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
- },
- "25020": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}"
- },
- "25021": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}"
- },
- "25022": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25023": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid compatibility information. {additionalInfo}"
- },
- "25026": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Selling limit exceeded. {additionalInfo}"
- },
- "25097": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This listing is on hold due to a policy violation, and revisions are not possible. Please check your email for more information."
- },
- "25501": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture. {additionalInfo}"
- },
- "25502": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute information. {additionalInfo}"
- },
- "25503": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid product information. {additionalInfo}"
- },
- "25601": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{fieldName} is an invalid attribute. "
- },
- "25604": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25701": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "One or more of the supplied SKU(s) could not be found in the system."
- },
- "25702": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{skuValue} could not be found or is not available in the system."
- },
- "25707": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This is an invalid value for a SKU. Only alphanumeric characters can be used for SKUs, and their length must not exceed 50 characters."
- },
- "25708": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid SKU."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}"
- },
- "25710": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "We didn't find the resource/entity you are requesting. Please verify the request."
- },
- "25713": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This Offer is not available : {additionalInfo}."
- },
- "25715": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid values for dimensions and/or weight of shipping package."
- },
- "25759": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{replaceable_value} transaction is not possible as the parent listing is on-hold. Please check your email for further information. "
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- },
- "25025": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "delete": {
- "tags": [
- "inventory_item"
- ],
- "description": "This call is used to delete an inventory item record associated with a specified SKU. A successful call will not only delete that inventory item record, but will also have the following effects:- Delete any and all unpublished offers associated with that SKU;
- Delete any and all single-variation eBay listings associated with that SKU;
- Automatically remove that SKU from a multiple-variation listing and remove that SKU from any and all inventory item groups in which that SKU was a member.
The authorization header is the only required HTTP header for this call. See the HTTP request headers section for more information.
",
- "operationId": "deleteInventoryItem",
- "parameters": [
- {
- "name": "sku",
- "in": "path",
- "description": "This path parameter specifies the seller-defined SKU value of the product whose inventory item record you wish to delete.
Use the getInventoryItems method to retrieve SKU values.
Max length: 50",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25702": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{skuValue} could not be found or is not available in the system."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}. {additionalInfo}"
- },
- "25710": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "We didn't find the resource/entity you are requesting. Please verify the request"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/inventory_item": {
- "get": {
- "tags": [
- "inventory_item"
- ],
- "description": "This call retrieves all inventory item records defined for the seller's account. The limit query parameter allows the seller to control how many records are returned per page, and the offset query parameter is used to retrieve a specific page of records. The seller can make multiple calls to scan through multiple pages of records. There is no request payload for this call.
The authorization header is the only required HTTP header for this call, and it is required for all Inventory API calls. See the HTTP request headers section for more information.
For those who prefer to retrieve numerous inventory item records by SKU value with one call (up to 25 at a time), the bulkGetInventoryItem method can be used.",
- "operationId": "getInventoryItems",
- "parameters": [
- {
- "name": "limit",
- "in": "query",
- "description": "The value passed in this query parameter sets the maximum number of records to return per page of data. Although this field is a string, the value passed in this field should be an integer from 1 to 200.
Min: 1
Max: 200
Default: 25",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "The value passed in this query parameter sets the page number to retrieve. The first page of records has a value of 0, the second page of records has a value of 1, and so on. If this query parameter is not set, its value defaults to 0, and the first page of records is returned. ",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/InventoryItems"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25706": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "You have provided invalid pagination values. {additionalInfo}."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}."
- },
- "25710": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "We didn't find the resource/entity you are requesting. Please verify the request"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/inventory_item/{sku}/product_compatibility": {
- "get": {
- "tags": [
- "product_compatibility"
- ],
- "description": "This call is used by the seller to retrieve the list of products that are compatible with the inventory item. The SKU value for the inventory item is passed into the call URI, and a successful call with return the compatible vehicle list associated with this inventory item. Product compatibility is currently only applicable to motor vehicle parts and accessory categories, but more categories may be supported in the future.",
- "operationId": "getProductCompatibility",
- "parameters": [
- {
- "name": "sku",
- "in": "path",
- "description": "This path parameter specifies the SKU (stock keeping unit) of the inventory item associated with the product compatibility list being retrieved.
Use the getInventoryItems method to retrieve SKU values.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Compatibility"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25702": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{skuValue} could not be found or is not available in the system."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}. {additionalInfo}"
- },
- "25710": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "We didn't find the resource/entity you are requesting. Please verify the request"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "put": {
- "tags": [
- "product_compatibility"
- ],
- "description": "This call is used by the seller to create or replace a list of products that are compatible with the inventory item. The inventory item is identified with a SKU value in the URI. Product compatibility is currently only applicable to motor vehicle parts and accessory categories, but more categories may be supported in the future.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.",
- "operationId": "createOrReplaceProductCompatibility",
- "parameters": [
- {
- "name": "Content-Language",
- "in": "header",
- "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "sku",
- "in": "path",
- "description": "This path parameter specifies the SKU (stock keeping unit) of the inventory item associated with the compatibility list being created.
Use the getInventoryItems method to retrieve SKU values.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "Details of the compatibility",
- "content": {
- "application/json": {
- "schema": {
- "description": "Details of the compatibility",
- "$ref": "#/components/schemas/Compatibility"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "headers": {
- "Content-Language": {
- "schema": {
- "type": "string",
- "description": "This response header sets the natural language that will be provided in the field values of the response payload."
- }
- }
+ "delete": {
+ "tags": [
+ "product_compatibility"
+ ],
+ "description": "This call is used by the seller to delete the list of products that are compatible with the inventory item that is associated with the compatible product list. The inventory item is identified with a SKU value in the URI. Product compatibility is currently only applicable to motor vehicle parts and accessory categories, but more categories may be supported in the future.",
+ "operationId": "deleteProductCompatibility",
+ "parameters": [
+ {
+ "name": "sku",
+ "in": "path",
+ "description": "This path parameter specifies the SKU (stock keeping unit) of the inventory item that is associated with the product compatibility list that is being deleted.
Use the getInventoryItems method to retrieve SKU values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25702": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{skuValue} could not be found or is not available in the system."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}. {additionalInfo}"
+ },
+ "25710": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "We didn't find the resource/entity you are requesting. Please verify the request"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. <additional_information>"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/inventory_item_group/{inventoryItemGroupKey}": {
+ "get": {
+ "tags": [
+ "inventory_item_group"
+ ],
+ "description": "This call retrieves the inventory item group for a given inventoryItemGroupKey value. The inventoryItemGroupKey value is passed in at the end of the call URI.",
+ "operationId": "getInventoryItemGroup",
+ "parameters": [
+ {
+ "name": "inventoryItemGroupKey",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the inventory item group being retrieved. This value is assigned by the seller when an inventory item group is created.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/InventoryItemGroup"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25705": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}. {additionalInfo}"
+ },
+ "25710": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "We didn't find the resource/entity you are requesting. Please verify the request"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BaseResponse"
- }
- }
+ "put": {
+ "tags": [
+ "inventory_item_group"
+ ],
+ "description": "Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call creates a new inventory item group or updates an existing inventory item group. It is up to sellers whether they want to create a complete inventory item group record right from the start, or sellers can provide only some information with the initial createOrReplaceInventoryItemGroup call, and then make one or more additional createOrReplaceInventoryItemGroup calls to complete the inventory item group record. Upon first creating an inventory item group record, the only required elements are the inventoryItemGroupKey identifier in the call URI, and the members of the inventory item group specified through the variantSKUs array in the request payload.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Inventory item group fields for a list of fields required to publish an offer.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.
In the case of updating/replacing an existing inventory item group, this call does a complete replacement of the existing inventory item group record, so all fields (including the member SKUs) that make up the inventory item group are required, regardless of whether their values changed. So, when replacing/updating an inventory item group record, it is advised that the seller run a getInventoryItemGroup call for that inventory item group to see all of its current values/settings/members before attempting to update the record. And if changes are made to an inventory item group that is part of a live, multiple-variation eBay listing, these changes automatically update the eBay listing. For example, if a SKU value is removed from the inventory item group, the corresponding product variation will be removed from the eBay listing as well.
In addition to the required inventory item group identifier and member SKUs, other key information that is set with this call include: - Title and description of the inventory item group. The string values provided in these fields will actually become the listing title and listing description of the listing once the first SKU of the inventory item group is published successfully
- Common aspects that inventory items in the group share
- Product aspects that vary within each product variation
- Links to images demonstrating the variations of the product, and these images should correspond to the product aspect that is set with the variesBy.aspectsImageVariesBy field
Note: For more information, see Creating and managing inventory item groups.",
+ "operationId": "createOrReplaceInventoryItemGroup",
+ "parameters": [
+ {
+ "name": "Content-Language",
+ "in": "header",
+ "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "inventoryItemGroupKey",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the inventory item group being created or updated. This identifier is defined by the seller.
This value cannot be changed once it is set.
Max Length: 50",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Details of the inventory Item Group",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Details of the inventory Item Group",
+ "$ref": "#/components/schemas/InventoryItemGroup"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "headers": {
+ "Content-Language": {
+ "schema": {
+ "type": "string",
+ "description": "This describes the natural language(s) of the intended audience for the enclosed entity"
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BaseResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25096": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This listing is on hold due to a policy violation. You may revise it to resolve the situation. Please check your email for more information."
+ },
+ "25124": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing requires a minimum 30-day return period and seller-paid return shipping. eBay automatically updated the listing's return policy settings to meet these requirements. Sellers using business policies should update their return business policy for future P&A listings. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25126": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Certification, Certification Number, Circulated/Uncirculated and Grade aspects will be deprecated in the near future. Please use the new condition grading conditions and descriptors."
+ },
+ "25401": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Invalid listing format removed {additionalInfo}"
+ },
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System warning. {additionalInfo}"
+ }
+ }
+ }
+ },
+ "201": {
+ "description": "Created",
+ "headers": {
+ "Content-Language": {
+ "schema": {
+ "type": "string",
+ "description": "This describes the natural language(s) of the intended audience for the enclosed entity"
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BaseResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25096": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This listing is on hold due to a policy violation. You may revise it to resolve the situation. Please check your email for more information."
+ },
+ "25124": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing requires a minimum 30-day return period and seller-paid return shipping. eBay automatically updated the listing's return policy settings to meet these requirements. Sellers using business policies should update their return business policy for future P&A listings. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25126": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Certification, Certification Number, Circulated/Uncirculated and Grade aspects will be deprecated in the near future. Please use the new condition grading conditions and descriptors."
+ },
+ "25401": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Invalid listing format removed {additionalInfo}"
+ },
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System warning. {additionalInfo}"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "A user error has occurred. {additionalInfo}"
+ },
+ "25003": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}"
+ },
+ "25004": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}"
+ },
+ "25005": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}"
+ },
+ "25006": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}"
+ },
+ "25007": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}"
+ },
+ "25008": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}"
+ },
+ "25009": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}"
+ },
+ "25011": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}"
+ },
+ "25012": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid inventory location. {additionalInfo}"
+ },
+ "25013": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
+ },
+ "25014": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}"
+ },
+ "25015": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}"
+ },
+ "25016": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The {fieldName} value is invalid. {additionalInfo}"
+ },
+ "25017": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
+ },
+ "25018": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
+ },
+ "25019": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
+ },
+ "25020": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}"
+ },
+ "25021": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}"
+ },
+ "25022": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25023": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid compatibility information. {additionalInfo}"
+ },
+ "25024": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid Best Offer information. {additionalInfo}"
+ },
+ "25026": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Selling limit exceeded. {additionalInfo}"
+ },
+ "25041": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s)."
+ },
+ "25042": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, free shipping must be provided."
+ },
+ "25043": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, returns must be accepted."
+ },
+ "25044": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, refund must be provided as Money Back."
+ },
+ "25045": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days."
+ },
+ "25046": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, seller must pay the cost for return shipping."
+ },
+ "25047": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition"
+ },
+ "25048": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition in this Category"
+ },
+ "25049": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition for the selected Brand"
+ },
+ "25050": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title."
+ },
+ "25051": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle"
+ },
+ "25052": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, at least {replaceable_value} images must be provided"
+ },
+ "25097": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This listing is on hold due to a policy violation, and revisions are not possible. Please check your email for more information."
+ },
+ "25098": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{replaceable_value} transaction is not possible as the parent listing is on-hold. Please check your email for further information. "
+ },
+ "25120": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing in {categoryName}, key information such as {fieldName} comes from eBayās catalog and should be left blank."
+ },
+ "25121": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing in {categoryName}, sellers are required to adopt eBayās catalog data which will provide all the necessary details for the product."
+ },
+ "25123": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing has a non-compliant domestic return policy. Please update the return window to 30-days (or more) and/or update return shipping cost payer to Seller, and then make another call. Sellers using business policies must make the same changes to their return business policy and then make another call. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25701": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "One or more of the supplied SKU(s) could not be found in the system."
+ },
+ "25702": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{skuValue} could not be found or is not available in the system."
+ },
+ "25703": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The following SKU is already a member of another group. SKU : {skuValue} groupId : {inventoryItemGroupKey}"
+ },
+ "25704": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The following SKU is already listed as a single SKU listing. SKU : {skuValue} Listing ID : {listingId}"
+ },
+ "25705": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}. {additionalInfo}"
+ },
+ "25756": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Auction format is not permitted with a SKU that is part of an InventoryItemGroup."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ },
+ "25025": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "x-response-codes": {
- "errors": {
- "25401": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Invalid listing format removed. {additionalInfo}"
- },
- "25402": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System warning. {additionalInfo}"
- }
- }
- }
- },
- "201": {
- "description": "Created",
- "headers": {
- "Content-Language": {
- "schema": {
- "type": "string",
- "description": "This response header sets the natural language that will be provided in the field values of the response payload."
- }
- }
+ "delete": {
+ "tags": [
+ "inventory_item_group"
+ ],
+ "description": "This call deletes the inventory item group for a given inventoryItemGroupKey value.",
+ "operationId": "deleteInventoryItemGroup",
+ "parameters": [
+ {
+ "name": "inventoryItemGroupKey",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the inventory item group being deleted. This value is assigned by the seller when an inventory item group is created.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25705": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}. {additionalInfo}"
+ },
+ "25710": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "We didn't find the resource/entity you are requesting. Please verify the request"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/bulk_migrate_listing": {
+ "post": {
+ "tags": [
+ "listing"
+ ],
+ "description": "This call is used to convert existing eBay Listings to the corresponding Inventory API objects. If an eBay listing is successfully migrated to the Inventory API model, new Inventory Location, Inventory Item, and Offer objects are created. For a multiple-variation listing that is successfully migrated, in addition to the three new Inventory API objects just mentioned, an Inventory Item Group object will also be created. If the eBay listing is a motor vehicle part or accessory listing with a compatible vehicle list (ItemCompatibilityList container in Trading API's Add/Revise/Relist/Verify calls), a Product Compatibility object will be created.
Migration Requirements
To be eligible for migration, the active eBay listings must meet the following requirements:
Unsupported Listing Features
The following features are not yet available to be set or modified through the Inventory API, but they will remain on the active eBay listing, even after a successful migration to the Inventory model. The downside to this is that the seller will be completely blocked (in APIs or My eBay) from revising these features/settings once the migration takes place:- Any listing-level Buyer Requirements
- Listing enhancements like a bold listing title or Gallery Plus
Making the Call
In the request payload of the bulkMigrateListings call, the seller will pass in an array of one to five eBay listing IDs (aka Item IDs). To save time and hassle, that seller should do a pre-check on each listing to make sure those listings meet the requirements to be migrated to the new Inventory model. This method also requires the Content-Type request header. See the HTTP request headers for more information. There are no path or query parameters for this call.
Call Response
If an eBay listing is migrated successfully to the new Inventory model, the following will occur:- An Inventory Item object will be created for the item(s) in the listing, and this object will be accessible through the Inventory API
- An Offer object will be created for the listing, and this object will be accessible through the Inventory API
- An Inventory Location object will be created and associated with the Offer object, as an Inventory Location must be associated with a published Offer
The response payload of the Bulk Migrate Listings call will show the results of each listing migration. These results include an HTTP status code to indicate the success or failure of each listing migration, the SKU value associated with each item, and if the migration is successful, an Offer ID value. The SKU value will be used in the Inventory API to manage the Inventory Item object, and the Offer ID value will be used in the Inventory API to manage the Offer object. Errors and/or warnings containers will be returned for each listing where an error and/or warning occurred with the attempted migration.
If a multiple-variation listing is successfully migrated, along with the Offer and Inventory Location objects, an Inventory Item object will be created for each product variation within the listing, and an Inventory Item Group object will also be created, grouping those variations together in the Inventory API platform. For a motor vehicle part or accessory listing that has a specified list of compatible vehicles, in addition to the Inventory Item, Inventory Location, and Offer objects that are created, a Product Compatibility object will also be created in the Inventory API platform.",
+ "operationId": "bulkMigrateListing",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Details of the listings that needs to be migrated into Inventory",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Details of the listings that needs to be migrated into Inventory",
+ "$ref": "#/components/schemas/BulkMigrateListing"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkMigrateListingResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi-Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25718": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Cannot migrate listing. {additionalInfo}"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Any System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/listing/{listingId}/sku/{sku}/locations": {
+ "get": {
+ "tags": [
+ "listing"
+ ],
+ "description": "This method allows sellers to retrieve the locations mapped to a specific SKU within a listing.
The listingId and sku of the listing are passed in as path parameters. This method only retrieves location mappings for a single SKU value; if a seller wishes to retrieve the location mappings for all items in a multiple-variation listing, this method must be called for each variation in the listing.
If there are fulfillment center locations mapped to the SKU, they will be returned in the locations array. If no locations are mapped to the SKU, status code 404 Not Found will be returned.",
+ "operationId": "getSkuLocationMapping",
+ "parameters": [
+ {
+ "name": "listingId",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the listing that the SKU belongs to for which all mapped locations will be retrieved.
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all listing IDs for all active listings.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sku",
+ "in": "path",
+ "description": "This path parameter specifies the seller-defined SKU value of the item/variation for which location mappings will be retrieved. This SKU value must be defined in the listing specified in listingId parameter
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all SKUs for all active listings.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/LocationMapping"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Any User error. {additionalInfo}"
+ },
+ "25904": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid listing ID or the listing does not belong to the seller."
+ },
+ "25905": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid SKU value or the SKU value is not defined in the listing."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Any System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly"
+ ]
+ }
+ ]
},
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BaseResponse"
- }
- }
+ "put": {
+ "tags": [
+ "listing"
+ ],
+ "description": "This method allows sellers to map multiple fulfillment center locations to single-SKU listing, or to a single SKU within a multiple-variation listing. This allows eBay to leverage the location metadata associated with a sellerās fulfillment centers to calculate more accurate estimated delivery dates on their listing.
Note: While location mappings can be created for listings on any eBay marketplace, the improved delivery date estimate feature is currently only supported for US-based fulfillment centers shipping domestically within the US.
The listing for which the locations will be mapped is specified through the listingId and sku values associated with the item. Note that only a single SKU value can be identified; if the seller wishes to map locations to multiple/all SKU values in a multiple-variation listing, this method must be called for each of those SKUs within the listing.
Note: Sellers should keep track of listingId/sku pairs that have been used for location mapping, as there is no programmatic way to retrieve or delete these pairs at this time.
In the case of replacing/updating existing location mappings, this method will do a complete replacement of the location mappings associated with a SKU. This means that each existing location mappings that the seller wants to continue to associate with the SKU are required in the update call, regardless of if they are affected by the update.
This method is only supported for inventory locations that have FULFILLMENT_CENTER as one of their locationTypes. For more information on fulfillment center locations, see Create a fulfillment center location.
For more information on location mapping features, see Multi-warehouse program in the Selling Integration Guide.
Note: Only listings with SKU values are supported. Sellers using listings creating through the Trading API can add a SKU value to their single variation listing through the Item.SKU field during listing creation or by using the ReviseItem family of calls.",
+ "operationId": "createOrReplaceSkuLocationMapping",
+ "parameters": [
+ {
+ "name": "listingId",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the listing for which multiple fulfillment center locations will be mapped to a SKU within that listing.
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all listing IDs for all active listings.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sku",
+ "in": "path",
+ "description": "This path parameter specifies the seller-defined SKU value of the item/variation for which multiple fulfillment center locations will be mapped. This SKU value must be defined in the listing specified in listingId parameter.
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all listing IDs for all active listings.
Note: SKU values can be updated by a seller at any time. If a seller updates a SKU value that is being used for location mapping, this change will not be reflected until the mapping is updated through the createOrReplaceSkuLocationMapping method.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/LocationMapping"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Any User error. {additionalInfo}"
+ },
+ "25900": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "One or more inventory locations could not be found for the seller."
+ },
+ "25901": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Missing a location. Please specify one or more inventory locations."
+ },
+ "25902": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "One or more duplicate inventory locations were specified. Unique inventory locations must be used."
+ },
+ "25904": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid listing ID or the listing does not belong to the seller."
+ },
+ "25905": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid SKU value or the SKU value is not defined in the listing."
+ },
+ "25906": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The provided inventory location must be a Fulfillment Center. Please use a Fulfillment Center location or use updateInventoryLocation to change location type to FULFILLMENT_CENTER."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Any System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "x-response-codes": {
- "errors": {
- "25401": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Invalid listing format removed. {additionalInfo}"
- },
- "25402": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System warning. {additionalInfo}"
- }
- }
- }
- },
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "A user error has occurred. {additionalInfo}"
- },
- "25003": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}"
- },
- "25004": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}"
- },
- "25005": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}"
- },
- "25006": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}"
- },
- "25007": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}"
- },
- "25008": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}"
- },
- "25009": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}"
- },
- "25011": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}"
- },
- "25012": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid inventory location. {additionalInfo}"
- },
- "25013": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
- },
- "25014": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}"
- },
- "25015": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}"
- },
- "25016": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The {fieldName} value is invalid. {additionalInfo}"
- },
- "25017": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
- },
- "25018": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
- },
- "25019": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
- },
- "25020": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}"
- },
- "25021": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}"
- },
- "25022": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25023": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid compatibility information. {additionalInfo}"
- },
- "25026": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Selling limit exceeded. {additionalInfo}"
- },
- "25702": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{skuValue} could not be found or is not available in the system."
- },
- "25739": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "User input error. The number of compatibilityProperties in the request cannot exceed {additionalInfo}."
- },
- "25740": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "User input error. Invalid name for compatibilityProperties. The length should be between 1 and {additionalInfo} characters."
- },
- "25741": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "User input error. Invalid value for compatibilityProperties. The length should be between 1 and {additionalInfo} characters."
- },
- "25742": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "User input error. productFamilyProperties and compatibilityProperties cannot be used together. Please use compatibilityProperties."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- },
- "25025": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "delete": {
- "tags": [
- "product_compatibility"
- ],
- "description": "This call is used by the seller to delete the list of products that are compatible with the inventory item that is associated with the compatible product list. The inventory item is identified with a SKU value in the URI. Product compatibility is currently only applicable to motor vehicle parts and accessory categories, but more categories may be supported in the future.",
- "operationId": "deleteProductCompatibility",
- "parameters": [
- {
- "name": "sku",
- "in": "path",
- "description": "This path parameter specifies the SKU (stock keeping unit) of the inventory item that is associated with the product compatibility list that is being deleted.
Use the getInventoryItems method to retrieve SKU values.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25702": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{skuValue} could not be found or is not available in the system."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}. {additionalInfo}"
- },
- "25710": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "We didn't find the resource/entity you are requesting. Please verify the request"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. <additional_information>"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/inventory_item_group/{inventoryItemGroupKey}": {
- "get": {
- "tags": [
- "inventory_item_group"
- ],
- "description": "This call retrieves the inventory item group for a given inventoryItemGroupKey value. The inventoryItemGroupKey value is passed in at the end of the call URI.",
- "operationId": "getInventoryItemGroup",
- "parameters": [
- {
- "name": "inventoryItemGroupKey",
- "in": "path",
- "description": "This path parameter specifies the unique identifier of the inventory item group being retrieved. This value is assigned by the seller when an inventory item group is created.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/InventoryItemGroup"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25705": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}. {additionalInfo}"
- },
- "25710": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "We didn't find the resource/entity you are requesting. Please verify the request"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "put": {
- "tags": [
- "inventory_item_group"
- ],
- "description": "Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call creates a new inventory item group or updates an existing inventory item group. It is up to sellers whether they want to create a complete inventory item group record right from the start, or sellers can provide only some information with the initial createOrReplaceInventoryItemGroup call, and then make one or more additional createOrReplaceInventoryItemGroup calls to complete the inventory item group record. Upon first creating an inventory item group record, the only required elements are the inventoryItemGroupKey identifier in the call URI, and the members of the inventory item group specified through the variantSKUs array in the request payload.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Inventory item group fields for a list of fields required to publish an offer.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.
In the case of updating/replacing an existing inventory item group, this call does a complete replacement of the existing inventory item group record, so all fields (including the member SKUs) that make up the inventory item group are required, regardless of whether their values changed. So, when replacing/updating an inventory item group record, it is advised that the seller run a getInventoryItemGroup call for that inventory item group to see all of its current values/settings/members before attempting to update the record. And if changes are made to an inventory item group that is part of a live, multiple-variation eBay listing, these changes automatically update the eBay listing. For example, if a SKU value is removed from the inventory item group, the corresponding product variation will be removed from the eBay listing as well.
In addition to the required inventory item group identifier and member SKUs, other key information that is set with this call include: - Title and description of the inventory item group. The string values provided in these fields will actually become the listing title and listing description of the listing once the first SKU of the inventory item group is published successfully
- Common aspects that inventory items in the group share
- Product aspects that vary within each product variation
- Links to images demonstrating the variations of the product, and these images should correspond to the product aspect that is set with the variesBy.aspectsImageVariesBy field
Note: For more information, see Creating and managing inventory item groups.",
- "operationId": "createOrReplaceInventoryItemGroup",
- "parameters": [
- {
- "name": "Content-Language",
- "in": "header",
- "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "inventoryItemGroupKey",
- "in": "path",
- "description": "This path parameter specifies the unique identifier of the inventory item group being created or updated. This identifier is defined by the seller.
This value cannot be changed once it is set.
Max Length: 50",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "Details of the inventory Item Group",
- "content": {
- "application/json": {
- "schema": {
- "description": "Details of the inventory Item Group",
- "$ref": "#/components/schemas/InventoryItemGroup"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "headers": {
- "Content-Language": {
- "schema": {
- "type": "string",
- "description": "This describes the natural language(s) of the intended audience for the enclosed entity"
- }
- }
+ "delete": {
+ "tags": [
+ "listing"
+ ],
+ "description": "This method allows sellers to remove all location mappings associated with a specific SKU within a listing.
The listingId and sku of the listing are passed in as path parameters.
Important! To remove all location mappings from a multiple-variation listing, this method must be used for each individual SKU in the listing.
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all listing IDs for all active listings.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sku",
+ "in": "path",
+ "description": "This path parameter specifies the seller-defined SKU value of the item/variation for which location mappings will be removed. This SKU value must be defined in the listing specified in listingId parameter
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all SKUs for all active listings.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Any User error. {additionalInfo}"
+ },
+ "25904": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid listing ID or the listing does not belong to the seller."
+ },
+ "25905": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid SKU value or the SKU value is not defined in the listing."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Any System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/bulk_create_offer": {
+ "post": {
+ "tags": [
+ "offer"
+ ],
+ "description": "This call creates multiple offers (up to 25) for specific inventory items on a specific eBay marketplace. Although it is not a requirement for the seller to create complete offers (with all necessary details) right from the start, eBay recommends that the seller provide all necessary details with this call since there is currently no bulk operation available to update multiple offers with one call. The following fields are always required in the request payload: sku, marketplaceId, and (listing) format.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Offer fields for a list of fields required to publish an offer.
Other information that will be required before a offer can be published are highlighted below: - Inventory location
- Offer price
- Available quantity
- eBay listing category
- Referenced listing policy profiles to set payment, return, and fulfillment values/settings
Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to true if omitted.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.
If the call is successful, unique offerId values are returned in the response for each successfully created offer. The offerId value will be required for many other offer-related calls. Note that this call only stages an offer for publishing. The seller must run either the publishOffer, bulkPublishOffer, or publishOfferByInventoryItemGroup call to convert offer(s) into an active single- or multiple-variation listing.
For those who prefer to create a single offer per call, the createOffer method can be used instead.
",
+ "operationId": "bulkCreateOffer",
+ "parameters": [
+ {
+ "name": "Content-Language",
+ "in": "header",
+ "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Details of the offer for the channel",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Details of the offer for the channel",
+ "$ref": "#/components/schemas/BulkEbayOfferDetailsWithKeys"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkOfferResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi-Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25702": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "SKU {additionalInfo} is not available in the system"
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid request. Invalid value for field {additionalInfo}"
+ },
+ "25729": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The combination of SKU, marketplaceId and format should be unique."
+ },
+ "25730": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The number of offers in the request cannot exceed {additionalInfo}"
+ },
+ "25735": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid SKU, marketplaceId or format."
+ },
+ "25752": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate provided is invalid."
+ },
+ "25755": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingDuration is required for auction offer."
+ },
+ "25756": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Auction format is not permitted with a SKU that is part of an InventoryItemGroup."
+ },
+ "25757": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "auctionStartPrice is required for auction offer."
+ },
+ "25758": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "auctionStartPrice and auctionReservePrice are not supported for fixed price offer."
+ },
+ "25761": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Discount pricing is not applicable for auction offer."
+ },
+ "25762": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "availableQuantity is not applicable for auction offer."
+ },
+ "25763": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "quantityLimitPerBuyer is not applicable for auction offer."
+ },
+ "25764": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "eBayPlusIfEligible is not applicable for auction offer."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Any System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/bulk_publish_offer": {
+ "post": {
+ "tags": [
+ "offer"
+ ],
+ "description": "Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call is used to convert unpublished offers (up to 25) into published offers, or live eBay listings. The unique identifier (offerId) of each offer to publish is passed into the request payload. It is possible that some unpublished offers will be successfully created into eBay listings, but others may fail. The response payload will show the results for each offerId value that is passed into the request payload. The errors and warnings containers will be returned for an offer that had one or more issues being published.
Important!Publish offer note: Fields may be optional or conditionally required when calling the create or update methods, but become required when publishing the offer to create active listings. For this method, see Offer fields for a list of fields required to publish an offer.
For those who prefer to publish one offer per call, the publishOffer method can be used instead. In the case of a multiple-variation listing, the publishOfferByInventoryItemGroup call should be used instead, as this call will convert all unpublished offers associated with an inventory item group into a multiple-variation listing.",
+ "operationId": "bulkPublishOffer",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The base request of the bulkPublishOffer method.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The base request of the bulkPublishOffer method.",
+ "$ref": "#/components/schemas/BulkOffer"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkPublishResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25028": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not applicable and has been dropped"
+ },
+ "25030": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not applicable for the condition and has been dropped"
+ },
+ "25033": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Duplicate policy IDs found"
+ },
+ "25037": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Item level Eco Participation Fee will be ignored"
+ },
+ "25124": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing requires a minimum 30-day return period and seller-paid return shipping. eBay automatically updated the listing's return policy settings to meet these requirements. Sellers using business policies should update their return business policy for future P&A listings. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25126": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Certification, Certification Number, Circulated/Uncirculated and Grade aspects will be deprecated in the near future. Please use the new condition grading conditions and descriptors."
+ },
+ "25401": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Invalid listing options removed. {additionalInfo}"
+ },
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System warning. {additionalInfo}"
+ },
+ "25753": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi-Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Any User error. {additionalInfo}"
+ },
+ "25003": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid price. {additionalInfo}"
+ },
+ "25004": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid quantity. {additionalInfo}"
+ },
+ "25005": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid category. {additionalInfo}"
+ },
+ "25006": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid listing option. {additionalInfo}"
+ },
+ "25007": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid Shipping policy information. {additionalInfo}"
+ },
+ "25008": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid Payment policy information. {additionalInfo}"
+ },
+ "25009": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid Return policy information. {additionalInfo}"
+ },
+ "25011": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid tax information. {additionalInfo}"
+ },
+ "25012": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid location. {additionalInfo}"
+ },
+ "25013": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
+ },
+ "25014": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid pictures. {additionalInfo}"
+ },
+ "25015": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid picture URL. {additionalInfo}"
+ },
+ "25016": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid {fieldName}. {additionalInfo}"
+ },
+ "25017": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
+ },
+ "25018": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
+ },
+ "25019": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
+ },
+ "25020": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid package details. {additionalInfo}"
+ },
+ "25021": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid condition information. {additionalInfo}"
+ },
+ "25022": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25023": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid compatibility information. {additionalInfo}"
+ },
+ "25026": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Selling limits exceeded. {additionalInfo}"
+ },
+ "25029": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is required for this category."
+ },
+ "25031": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not valid and needs to be a number between {min} and {max}"
+ },
+ "25032": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not valid"
+ },
+ "25034": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Only {max value} policies can be specified"
+ },
+ "25035": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The specified policy is not found for the market place"
+ },
+ "25036": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The policy(ies) {PolicyId} is not of type {PolicyEnum}"
+ },
+ "25038": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer or is ending within 12 hours"
+ },
+ "25039": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
+ },
+ "25040": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
+ },
+ "25041": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s)."
+ },
+ "25042": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, free shipping must be provided."
+ },
+ "25043": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, returns must be accepted."
+ },
+ "25044": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, refund must be provided as Money Back."
+ },
+ "25045": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days."
+ },
+ "25046": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, seller must pay the cost for return shipping."
+ },
+ "25047": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition"
+ },
+ "25048": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition in this Category"
+ },
+ "25049": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition for the selected Brand"
+ },
+ "25050": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title."
+ },
+ "25051": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle"
+ },
+ "25052": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, at least {replaceable_value} images must be provided"
+ },
+ "25076": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{replaceable_value} ID(s) {replaceable_value} not found. Please use valid ID(s)."
+ },
+ "25077": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Duplicate Regulatory ID(s) {replaceable_value} sent in the request. Duplicate ID(s) have been ignored."
+ },
+ "25078": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Hazmat structure incorrect for {replaceable_value}."
+ },
+ "25079": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Repair score invalid. Repair score must be in the range from {replaceable_value} to {replaceable_value} with one decimal place."
+ },
+ "25080": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The value of the {0} field is invalid. Field must not exceed {replaceable_value} characters."
+ },
+ "25081": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Hazardous material information incomplete. Your listing must include hazardous statements."
+ },
+ "25083": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Energy efficiency image is missing. Image is required with image description."
+ },
+ "25084": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The listing must have both an energy efficiency label and a product information sheet."
+ },
+ "25086": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The URL provided must be an eBay Picture Service URL."
+ },
+ "25088": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The email address provided is formatted incorrectly."
+ },
+ "25089": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} global compliance policies allowed. Excess policies ignored."
+ },
+ "25090": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} compliance policies per region allowed. Excess policies ignored."
+ },
+ "25091": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than a total of {replaceable_value} compliance policies allowed. Excess policies ignored."
+ },
+ "25092": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} global takeback policy allowed."
+ },
+ "25093": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} takeback policy per region allowed. Excess policies ignored."
+ },
+ "25094": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than a total of {replaceable_value} takeback policies allowed."
+ },
+ "25095": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Region invalid for regional custom policy. Regions allowed are {replaceable_value}."
+ },
+ "25104": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Regulatory document ID(s) {replaceable_value} not found. Please use valid ID(s)."
+ },
+ "25106": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Regulatory document structure incorrect. Max allowed number of entries is {replaceable_value}."
+ },
+ "25107": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid document state for ID(s) {replaceable_value}. Documents must be in the SUBMITTED or ACCEPTED state."
+ },
+ "25108": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Product Safety structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
+ },
+ "25109": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Product safety information incomplete. Your listing must include pictograms or safety statements."
+ },
+ "25110": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Manufacturer address information is incomplete. When providing the address, please provide the street, city, postal code and country"
+ },
+ "25111": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Manufacturer information is incomplete. Please provide the company name."
+ },
+ "25112": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
+ },
+ "25113": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person address information is incomplete. When providing the address, please provide the street, city, postal code and country"
+ },
+ "25114": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person information is incomplete. Please provide the company name."
+ },
+ "25115": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Either the Manufacturer or at least one of the Responsible Persons must be located in the EU."
+ },
+ "25116": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Please provide a minimum of {replaceable_value} and a maximum of {replaceable_value} types for a Responsible Person."
+ },
+ "25118": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller must provide at least one form of contact info for Manufacturer - either address, email, contact URL or phone."
+ },
+ "25119": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller must provide at least one form of contact info for Responsible Person - either address, email, contact URL or phone."
+ },
+ "25120": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing in {categoryName}, key information such as {fieldName} comes from eBayās catalog and should be left blank."
+ },
+ "25121": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing in {categoryName}, sellers are required to adopt eBayās catalog data which will provide all the necessary details for the product."
+ },
+ "25122": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The contact URL is incorrectly formatted. Please update the formatting."
+ },
+ "25123": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing has a non-compliant domestic return policy. Please update the return window to 30-days (or more) and/or update return shipping cost payer to Seller, and then make another call. Sellers using business policies must make the same changes to their return business policy and then make another call. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25601": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25604": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid offerId"
+ },
+ "25713": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This Offer is not available : {additionalInfo}."
+ },
+ "25730": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The number of offers in the request cannot exceed {additionalInfo}."
+ },
+ "25731": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "OfferId should be unique in the request."
+ },
+ "25732": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Offers associated with SKUs that are part of a variation group cannot be published using this endpoint."
+ },
+ "25752": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate provided is invalid."
+ },
+ "25760": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "shipToLocationAvailability quantity insufficient to create auction listings."
+ },
+ "25766": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The takeBackPolicyId field must be a long value type. Please correct the error."
+ },
+ "25767": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The productCompliancePolicyId field must be a long value type. Please correct the error."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Any System error. {additionalInfo}"
+ },
+ "25025": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Concurrent access of Inventory or InventoryItemGroup. Please try again later"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/offer": {
+ "get": {
+ "tags": [
+ "offer"
+ ],
+ "description": "This call retrieves all existing offers for the specified SKU value. The seller has the option of limiting the offers that are retrieved to a specific eBay marketplace, or to a listing format.
Note: At this time, the same SKU value can not be offered across multiple eBay marketplaces, so the marketplace_id query parameter currently does not have any practical use for this call.
Note: The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, getOffers will return two offers. Otherwise, only one offer will be returned.
The authorization header is the only required HTTP header for this call. See the HTTP request headers section for more information.",
+ "operationId": "getOffers",
+ "parameters": [
+ {
+ "name": "format",
+ "in": "query",
+ "description": "This enumeration value sets the listing format for the offers being retrieved. This query parameter will be passed in if the seller only wants to see offers in a specified listing format, such as FIXED_PRICE.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The value passed in this query parameter sets the maximum number of records to return per page of data. Although this field is a string, the value passed in this field should be a positive integer value. If this query parameter is not set, up to 100 records will be returned on each page of results.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "query",
+ "description": "The unique identifier of the eBay marketplace. This query parameter will be passed in if the seller only wants to see the product's offers on a specific eBay marketplace.
Note: At this time, the same SKU value can not be offered across multiple eBay marketplaces, so the marketplace_id query parameter currently does not have any practical use for this call.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "The value passed in this query parameter sets the page number to retrieve. Although this field is a string, the value passed in this field should be a integer value equal to or greater than 0. The first page of records has a value of 0, the second page of records has a value of 1, and so on. If this query parameter is not set, its value defaults to 0, and the first page of records is returned.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sku",
+ "in": "query",
+ "description": "The seller-defined SKU value is passed in as a query parameter. All offers associated with this product are returned in the response.
Note: The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, getOffers will return two offers. Otherwise, only one offer will be returned.
Use the getInventoryItems method to retrieve SKU values.
Max length: 50.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Offers"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25706": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "You have provided invalid pagination values. {additionalInfo}."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}. {additionalInfo}"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BaseResponse"
- }
- }
+ "post": {
+ "tags": [
+ "offer"
+ ],
+ "description": "This call creates an offer for a specific inventory item on a specific eBay marketplace. It is up to the sellers whether they want to create a complete offer (with all necessary details) right from the start, or sellers can provide only some information with the initial createOffer call, and then make one or more subsequent updateOffer calls to complete the offer and prepare to publish the offer. Upon first creating an offer, the following fields are required in the request payload: sku, marketplaceId, and (listing) format.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Offer fields for a list of fields required to publish an offer.
Other information that will be required before an offer can be published are highlighted below. These settings are either set with createOffer, or they can be set with a subsequent updateOffer call: - Inventory location
- Offer price
- Available quantity
- eBay listing category
- Referenced listing policy profiles to set payment, return, and fulfillment values/settings
Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to true if omitted.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.If the call is successful, a unique offerId value is returned in the response. This value will be required for many other offer-related calls. Note that this call only stages an offer for publishing. The seller must run the publishOffer call to convert the offer to an active eBay listing.
For those who prefer to create multiple offers (up to 25 at a time) with one call, the bulkCreateOffer method can be used.
",
+ "operationId": "createOffer",
+ "parameters": [
+ {
+ "name": "Content-Language",
+ "in": "header",
+ "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Details of the offer for the channel",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Details of the offer for the channel",
+ "$ref": "#/components/schemas/EbayOfferDetailsWithKeys"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "201": {
+ "description": "Created",
+ "headers": {
+ "Content-Language": {
+ "schema": {
+ "type": "string",
+ "description": "This response header sets the natural language that will be provided in the field values of the response payload."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/OfferResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25702": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{skuValue} could not be found or is not available in the system."
+ },
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}. {additionalInfo}"
+ },
+ "25752": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate provided is invalid."
+ },
+ "25755": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingDuration is required for auction offer."
+ },
+ "25756": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Auction format is not permitted with a SKU that is part of an InventoryItemGroup."
+ },
+ "25757": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "auctionStartPrice is required for auction offer."
+ },
+ "25758": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "auctionStartPrice and auctionReservePrice are not supported for fixed price offer."
+ },
+ "25761": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Discount pricing is not applicable for auction offer."
+ },
+ "25762": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "availableQuantity is not applicable for auction offer."
+ },
+ "25763": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "quantityLimitPerBuyer is not applicable for auction offer."
+ },
+ "25764": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "eBayPlusIfEligible is not applicable for auction offer."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/offer/{offerId}": {
+ "get": {
+ "tags": [
+ "offer"
+ ],
+ "description": "This call retrieves a specific published or unpublished offer. The unique identifier of the offer (offerId) is passed in at the end of the call URI.The authorization header is the only required HTTP header for this call. See the HTTP request headers section for more information.
",
+ "operationId": "getOffer",
+ "parameters": [
+ {
+ "name": "offerId",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the offer that is to be retrieved.
Use the getOffers method to retrieve offer IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/EbayOfferDetailsWithAll"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}. {additionalInfo}"
+ },
+ "25713": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This Offer is not available : {additionalInfo}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "x-response-codes": {
- "errors": {
- "25096": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This listing is on hold due to a policy violation. You may revise it to resolve the situation. Please check your email for more information."
- },
- "25401": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Invalid listing format removed {additionalInfo}"
- },
- "25402": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System warning. {additionalInfo}"
- }
- }
- }
- },
- "201": {
- "description": "Created",
- "headers": {
- "Content-Language": {
- "schema": {
- "type": "string",
- "description": "This describes the natural language(s) of the intended audience for the enclosed entity"
- }
- }
+ "put": {
+ "tags": [
+ "offer"
+ ],
+ "description": "This call updates an existing offer. An existing offer may be in published state (active eBay listing), or in an unpublished state and yet to be published with the publishOffer call. The unique identifier (offerId) for the offer to update is passed in at the end of the call URI.
The updateOffer call does a complete replacement of the existing offer object, so all fields that make up the current offer object are required, regardless of whether their values changed.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Offer fields for a list of fields required to publish an offer.
Other information that is required before an unpublished offer can be published or before a published offer can be revised include: - Inventory location
- Offer price
- Available quantity
- eBay listing category
- Referenced listing policy profiles to set payment, return, and fulfillment values/settings
Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to true if omitted from both the updateOffer and the createOffer calls. If a value is specified in the updateOffer call, this value will be used.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
For published offers, the listingDescription field is also required to update the offer/eBay listing. For unpublished offers, this field is not necessarily required unless it is already set for the unpublished offer.
",
+ "operationId": "updateOffer",
+ "parameters": [
+ {
+ "name": "Content-Language",
+ "in": "header",
+ "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offerId",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the offer being updated.
Use the getOffers method to retrieve offer IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Details of the offer for the channel",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Details of the offer for the channel",
+ "$ref": "#/components/schemas/EbayOfferDetailsWithId"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "headers": {
+ "Content-Language": {
+ "schema": {
+ "type": "string",
+ "description": "This response header sets the natural language that will be provided in the field values of the response payload."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/OfferResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25028": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not applicable and has been dropped"
+ },
+ "25030": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not applicable for the condition and has been dropped"
+ },
+ "25033": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Duplicate policy IDs found"
+ },
+ "25037": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Item level Eco Participation Fee will be ignored"
+ },
+ "25124": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing requires a minimum 30-day return period and seller-paid return shipping. eBay automatically updated the listing's return policy settings to meet these requirements. Sellers using business policies should update their return business policy for future P&A listings. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25126": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Certification, Certification Number, Circulated/Uncirculated and Grade aspects will be deprecated in the near future. Please use the new condition grading conditions and descriptors."
+ },
+ "25401": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Invalid listing options removed. {additionalInfo}"
+ },
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System warning. {additionalInfo}"
+ },
+ "25753": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "A user error has occurred. {additionalInfo}"
+ },
+ "25003": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}"
+ },
+ "25004": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}"
+ },
+ "25005": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}"
+ },
+ "25006": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}"
+ },
+ "25007": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}"
+ },
+ "25008": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}"
+ },
+ "25009": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}"
+ },
+ "25011": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}"
+ },
+ "25012": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid inventory location. {additionalInfo}"
+ },
+ "25013": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
+ },
+ "25014": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}"
+ },
+ "25015": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}"
+ },
+ "25016": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The {fieldName} value is invalid. {additionalInfo}"
+ },
+ "25017": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
+ },
+ "25018": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
+ },
+ "25019": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
+ },
+ "25020": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}"
+ },
+ "25021": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}"
+ },
+ "25022": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25023": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid compatibility information. {additionalInfo}"
+ },
+ "25026": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Selling limit exceeded. {additionalInfo}"
+ },
+ "25029": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is required for this category."
+ },
+ "25031": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not valid and needs to be a number between {min} and {max}"
+ },
+ "25032": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not valid"
+ },
+ "25034": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Only {max value} policies can be specified"
+ },
+ "25035": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The specified policy is not found for the market place"
+ },
+ "25036": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The policy(ies) {PolicyId} is not of type {PolicyEnum}"
+ },
+ "25038": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer or is ending within 12 hours"
+ },
+ "25039": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
+ },
+ "25040": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
+ },
+ "25076": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{replaceable_value} ID(s) {replaceable_value} not found. Please use valid ID(s)."
+ },
+ "25077": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Duplicate Regulatory ID(s) {replaceable_value} sent in the request. Duplicate ID(s) have been ignored."
+ },
+ "25078": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Hazmat structure incorrect for {replaceable_value}."
+ },
+ "25079": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Repair score invalid. Repair score must be in the range from {replaceable_value} to {replaceable_value} with one decimal place."
+ },
+ "25080": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The value of the {0} field is invalid. Field must not exceed {replaceable_value} characters."
+ },
+ "25081": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Hazardous material information incomplete. Your listing must include hazardous statements."
+ },
+ "25083": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Energy efficiency image is missing. Image is required with image description."
+ },
+ "25084": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The listing must have both an energy efficiency label and a product information sheet."
+ },
+ "25086": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The URL provided must be an eBay Picture Service URL."
+ },
+ "25088": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The email address provided is formatted incorrectly."
+ },
+ "25089": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} global compliance policies allowed. Excess policies ignored."
+ },
+ "25090": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} compliance policies per region allowed. Excess policies ignored."
+ },
+ "25091": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than a total of {replaceable_value} compliance policies allowed. Excess policies ignored."
+ },
+ "25092": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} global takeback policy allowed."
+ },
+ "25093": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} takeback policy per region allowed. Excess policies ignored."
+ },
+ "25094": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than a total of {replaceable_value} takeback policies allowed."
+ },
+ "25095": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Region invalid for regional custom policy. Regions allowed are {replaceable_value}."
+ },
+ "25104": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Regulatory document ID(s) {replaceable_value} not found. Please use valid ID(s)."
+ },
+ "25106": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Regulatory document structure incorrect. Max allowed number of entries is {replaceable_value}."
+ },
+ "25107": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid document state for ID(s) {replaceable_value}. Documents must be in the SUBMITTED or ACCEPTED state."
+ },
+ "25108": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Product Safety structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
+ },
+ "25109": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Product safety information incomplete. Your listing must include pictograms or safety statements."
+ },
+ "25110": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Manufacturer address information is incomplete. When providing the address, please provide the street, city, postal code and country"
+ },
+ "25111": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Manufacturer information is incomplete. Please provide the company name."
+ },
+ "25112": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
+ },
+ "25113": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person address information is incomplete. When providing the address, please provide the street, city, postal code and country"
+ },
+ "25114": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person information is incomplete. Please provide the company name."
+ },
+ "25115": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Either the Manufacturer or at least one of the Responsible Persons must be located in the EU."
+ },
+ "25116": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Please provide a minimum of {replaceable_value} and a maximum of {replaceable_value} types for a Responsible Person."
+ },
+ "25118": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller must provide at least one form of contact info for Manufacturer - either address, email, contact URL or phone."
+ },
+ "25119": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller must provide at least one form of contact info for Responsible Person - either address, email, contact URL or phone."
+ },
+ "25122": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The contact URL is incorrectly formatted. Please update the formatting."
+ },
+ "25123": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing has a non-compliant domestic return policy. Please update the return window to 30-days (or more) and/or update return shipping cost payer to Seller, and then make another call. Sellers using business policies must make the same changes to their return business policy and then make another call. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25601": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25604": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25710": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "We didn't find the resource/entity you are requesting. Please verify the request"
+ },
+ "25713": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This Offer is not available : {additionalInfo}."
+ },
+ "25752": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate provided is invalid."
+ },
+ "25756": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Auction format is not permitted with a SKU that is part of an InventoryItemGroup."
+ },
+ "25757": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "auctionStartPrice is required for auction offer."
+ },
+ "25758": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "auctionStartPrice and auctionReservePrice are not supported for fixed price offer."
+ },
+ "25761": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Discount pricing is not applicable for auction offer."
+ },
+ "25762": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "availableQuantity is not applicable for auction offer."
+ },
+ "25763": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "quantityLimitPerBuyer is not applicable for auction offer."
+ },
+ "25764": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "eBayPlusIfEligible is not applicable for auction offer."
+ },
+ "25766": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The takeBackPolicyId field must be a long value type. Please correct the error."
+ },
+ "25767": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The productCompliancePolicyId field must be a long value type. Please correct the error."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ },
+ "25025": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BaseResponse"
- }
- }
+ "delete": {
+ "tags": [
+ "offer"
+ ],
+ "description": "If used against an unpublished offer, this call will permanently delete that offer. In the case of a published offer (or live eBay listing), a successful call will either end the single-variation listing associated with the offer, or it will remove that product variation from the eBay listing and also automatically remove that product variation from the inventory item group. In the case of a multiple-variation listing, the deleteOffer will not remove the product variation from the listing if that variation has one or more sales. If that product variation has one or more sales, the seller can alternately just set the available quantity of that product variation to 0, so it is not available in the eBay search or View Item page, and then the seller can remove that product variation from the inventory item group at a later time.",
+ "operationId": "deleteOffer",
+ "parameters": [
+ {
+ "name": "offerId",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the offer being deleted.
Use the getOffers method to retrieve offer IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25713": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This Offer is not available : {additionalInfo}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/offer/get_listing_fees": {
+ "post": {
+ "tags": [
+ "offer"
+ ],
+ "description": "This call is used to retrieve the expected listing fees for up to 250 unpublished offers. An array of one or more offerId values are passed in under the offers container.
In the response payload, all listing fees are grouped by eBay marketplace, and listing fees per offer are not shown. A fees container will be returned for each eBay marketplace where the seller is selling the products associated with the specified offers.
Errors will occur if the seller passes in offerIds that represent published offers, so this call should be made before the seller publishes offers with the publishOffer.",
+ "operationId": "getListingFees",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "List of offers that needs fee information",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "List of offers that needs fee information",
+ "$ref": "#/components/schemas/OfferKeysWithId"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/FeesSummaryResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25709": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid value for {fieldName}. {additionalInfo}"
+ },
+ "25754": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "One or more provided offerId(s) are invalid. All offerId(s) in the request should belong to an inventoryItem or inventoryItemGroup for a specific marketplaceId and format."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/offer/{offerId}/publish": {
+ "post": {
+ "tags": [
+ "offer"
+ ],
+ "description": "Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call is used to convert an unpublished offer into a published offer, or live eBay listing. The unique identifier of the offer (offerId) is passed in at the end of the call URI.
Important!Publish offer note: Fields may be optional or conditionally required when calling the create or update methods, but become required when publishing the offer to create active listings. For this method, see Offer fields for a list of fields required to publish an offer.
For those who prefer to publish multiple offers (up to 25 at a time) with one call, the bulkPublishOffer method can be used. In the case of a multiple-variation listing, the publishOfferByInventoryItemGroup call should be used instead, as this call will convert all unpublished offers associated with an inventory item group into a multiple-variation listing.",
+ "operationId": "publishOffer",
+ "parameters": [
+ {
+ "name": "offerId",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the offer that is to be published.
Use the getOffers method to retrieve offer IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PublishResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25028": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not applicable and has been dropped"
+ },
+ "25030": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not applicable for the condition and has been dropped"
+ },
+ "25033": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Duplicate policy IDs found"
+ },
+ "25037": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Item level Eco Participation Fee will be ignored"
+ },
+ "25124": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing requires a minimum 30-day return period and seller-paid return shipping. eBay automatically updated the listing's return policy settings to meet these requirements. Sellers using business policies should update their return business policy for future P&A listings. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25126": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Certification, Certification Number, Circulated/Uncirculated and Grade aspects will be deprecated in the near future. Please use the new condition grading conditions and descriptors."
+ },
+ "25401": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid listing format removed {additionalInfo}"
+ },
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "System warning. {additionalInfo}"
+ },
+ "25753": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "A user error has occurred. {additionalInfo}"
+ },
+ "25003": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}"
+ },
+ "25004": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}"
+ },
+ "25005": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}"
+ },
+ "25006": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}"
+ },
+ "25007": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}"
+ },
+ "25008": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}"
+ },
+ "25009": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}"
+ },
+ "25011": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid tax information. {additionalInfo}"
+ },
+ "25012": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid inventory location. {additionalInfo}"
+ },
+ "25013": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
+ },
+ "25014": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}"
+ },
+ "25015": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}"
+ },
+ "25016": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The {fieldName} value is invalid. {additionalInfo}"
+ },
+ "25017": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
+ },
+ "25018": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
+ },
+ "25019": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
+ },
+ "25020": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}"
+ },
+ "25021": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}"
+ },
+ "25022": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25023": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid compatibility information. {additionalInfo}"
+ },
+ "25026": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Selling limit exceeded. {additionalInfo}"
+ },
+ "25029": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is required for this category."
+ },
+ "25031": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not valid and needs to be a number between {min} and {max}"
+ },
+ "25032": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not valid"
+ },
+ "25034": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Only {max value} policies can be specified"
+ },
+ "25035": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The specified policy is not found for the market place"
+ },
+ "25036": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The policy(ies) {PolicyId} is not of type {PolicyEnum}"
+ },
+ "25038": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer or is ending within 12 hours"
+ },
+ "25039": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
+ },
+ "25040": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
+ },
+ "25041": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s)."
+ },
+ "25042": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, free shipping must be provided."
+ },
+ "25043": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, returns must be accepted."
+ },
+ "25044": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, refund must be provided as Money Back."
+ },
+ "25045": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days."
+ },
+ "25046": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, seller must pay the cost for return shipping."
+ },
+ "25047": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition"
+ },
+ "25048": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition in this Category"
+ },
+ "25049": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition for the selected Brand"
+ },
+ "25050": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title."
+ },
+ "25051": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle"
+ },
+ "25052": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, at least {replaceable_value} images must be provided"
+ },
+ "25076": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{replaceable_value} ID(s) {replaceable_value} not found. Please use valid ID(s)."
+ },
+ "25077": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Duplicate Regulatory ID(s) {replaceable_value} sent in the request. Duplicate ID(s) have been ignored."
+ },
+ "25078": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Hazmat structure incorrect for {replaceable_value}."
+ },
+ "25079": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Repair score invalid. Repair score must be in the range from {replaceable_value} to {replaceable_value} with one decimal place."
+ },
+ "25080": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The value of the {0} field is invalid. Field must not exceed {replaceable_value} characters."
+ },
+ "25081": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Hazardous material information incomplete. Your listing must include hazardous statements."
+ },
+ "25083": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Energy efficiency image is missing. Image is required with image description."
+ },
+ "25084": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The listing must have both an energy efficiency label and a product information sheet."
+ },
+ "25086": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The URL provided must be an eBay Picture Service URL."
+ },
+ "25088": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The email address provided is formatted incorrectly."
+ },
+ "25089": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} global compliance policies allowed. Excess policies ignored."
+ },
+ "25090": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} compliance policies per region allowed. Excess policies ignored."
+ },
+ "25091": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than a total of {replaceable_value} compliance policies allowed. Excess policies ignored."
+ },
+ "25092": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} global takeback policy allowed."
+ },
+ "25093": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} takeback policy per region allowed. Excess policies ignored."
+ },
+ "25094": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than a total of {replaceable_value} takeback policies allowed."
+ },
+ "25095": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Region invalid for regional custom policy. Regions allowed are {replaceable_value}."
+ },
+ "25104": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Regulatory document ID(s) {replaceable_value} not found. Please use valid ID(s)."
+ },
+ "25106": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Regulatory document structure incorrect. Max allowed number of entries is {replaceable_value}."
+ },
+ "25107": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid document state for ID(s) {replaceable_value}. Documents must be in the SUBMITTED or ACCEPTED state."
+ },
+ "25108": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Product Safety structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
+ },
+ "25109": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Product safety information incomplete. Your listing must include pictograms or safety statements."
+ },
+ "25110": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Manufacturer address information is incomplete. When providing the address, please provide the street, city, postal code and country"
+ },
+ "25111": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Manufacturer information is incomplete. Please provide the company name."
+ },
+ "25112": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
+ },
+ "25113": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person address information is incomplete. When providing the address, please provide the street, city, postal code and country"
+ },
+ "25114": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person information is incomplete. Please provide the company name."
+ },
+ "25115": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Either the Manufacturer or at least one of the Responsible Persons must be located in the EU."
+ },
+ "25116": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Please provide a minimum of {replaceable_value} and a maximum of {replaceable_value} types for a Responsible Person."
+ },
+ "25118": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller must provide at least one form of contact info for Manufacturer - either address, email, contact URL or phone."
+ },
+ "25119": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller must provide at least one form of contact info for Responsible Person - either address, email, contact URL or phone."
+ },
+ "25120": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing in {categoryName}, key information such as {fieldName} comes from eBayās catalog and should be left blank."
+ },
+ "25121": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing in {categoryName}, sellers are required to adopt eBayās catalog data which will provide all the necessary details for the product."
+ },
+ "25122": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The contact URL is incorrectly formatted. Please update the formatting."
+ },
+ "25123": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing has a non-compliant domestic return policy. Please update the return window to 30-days (or more) and/or update return shipping cost payer to Seller, and then make another call. Sellers using business policies must make the same changes to their return business policy and then make another call. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25601": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{fieldName} is an invalid attribute."
+ },
+ "25604": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25713": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This Offer is not available : {additionalInfo}."
+ },
+ "25752": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate provided is invalid."
+ },
+ "25760": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "shipToLocationAvailability quantity insufficient to create auction listings."
+ },
+ "25766": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The takeBackPolicyId field must be a long value type. Please correct the error."
+ },
+ "25767": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The productCompliancePolicyId field must be a long value type. Please correct the error."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "A system error has occurred. {additionalInfo}"
+ },
+ "25025": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/offer/publish_by_inventory_item_group": {
+ "post": {
+ "tags": [
+ "offer"
+ ],
+ "description": "Note: Please note that any eBay listing created using the Inventory API cannot be revised or relisted using the Trading API calls.
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call is used to convert all unpublished offers associated with an inventory item group into an active, multiple-variation listing.
Important!Publish offer note: Fields may be optional or conditionally required when calling the create or update methods, but become required when publishing the offer to create active listings. For this method, see Offer fields for a list of fields required to publish an offer.
The unique identifier of the inventory item group (inventoryItemGroupKey) is passed in the request payload. All inventory items and their corresponding offers in the inventory item group must be valid (meet all requirements) for the publishOfferByInventoryItemGroup call to be completely successful. For any inventory items in the group that are missing required data or have no corresponding offers, the publishOfferByInventoryItemGroup will create a new multiple-variation listing, but any inventory items with missing required data/offers will not be in the newly-created listing. If any inventory items in the group to be published have invalid data, or one or more of the inventory items have conflicting data with one another, the publishOfferByInventoryItemGroup call will fail. Be sure to check for any error or warning messages in the call response for any applicable information about one or more inventory items/offers having issues.",
+ "operationId": "publishOfferByInventoryItemGroup",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The identifier of the inventory item group to publish and the eBay marketplace where the listing will be published is needed in the request payload.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The identifier of the inventory item group to publish and the eBay marketplace where the listing will be published is needed in the request payload.",
+ "$ref": "#/components/schemas/PublishByInventoryItemGroupRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PublishResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25028": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not applicable and has been dropped"
+ },
+ "25030": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not applicable for the condition and has been dropped"
+ },
+ "25033": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Duplicate policy IDs found"
+ },
+ "25037": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Item level Eco Participation Fee will be ignored"
+ },
+ "25124": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing requires a minimum 30-day return period and seller-paid return shipping. eBay automatically updated the listing's return policy settings to meet these requirements. Sellers using business policies should update their return business policy for future P&A listings. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25126": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Certification, Certification Number, Circulated/Uncirculated and Grade aspects will be deprecated in the near future. Please use the new condition grading conditions and descriptors."
+ },
+ "25401": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Invalid listing options removed. {additionalInfo}"
+ },
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System warning. {additionalInfo}"
+ },
+ "25753": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Any User error. {additionalInfo}"
+ },
+ "25003": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid price. {additionalInfo}"
+ },
+ "25004": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid quantity. {additionalInfo}"
+ },
+ "25005": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid category. {additionalInfo}"
+ },
+ "25006": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid listing option. {additionalInfo}"
+ },
+ "25007": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid Shipping policy information. {additionalInfo}"
+ },
+ "25008": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid Payment policy information. {additionalInfo}"
+ },
+ "25009": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid Return policy information. {additionalInfo}"
+ },
+ "25011": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid tax information. {additionalInfo}"
+ },
+ "25012": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid location. {additionalInfo}"
+ },
+ "25013": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
+ },
+ "25014": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid pictures. {additionalInfo}"
+ },
+ "25015": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid picture URL. {additionalInfo}"
+ },
+ "25016": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid {fieldName}. {additionalInfo}"
+ },
+ "25017": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
+ },
+ "25018": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
+ },
+ "25019": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
+ },
+ "25020": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid package details. {additionalInfo}"
+ },
+ "25021": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid condition information. {additionalInfo}"
+ },
+ "25022": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25023": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid compatibility information. {additionalInfo}"
+ },
+ "25026": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Selling limits exceeded. {additionalInfo}"
+ },
+ "25029": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is required for this category."
+ },
+ "25031": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not valid and needs to be a number between {min} and {max}"
+ },
+ "25032": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{field} is not valid"
+ },
+ "25034": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Only {max value} policies can be specified"
+ },
+ "25035": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The specified policy is not found for the market place"
+ },
+ "25036": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The policy(ies) {PolicyId} is not of type {PolicyEnum}"
+ },
+ "25038": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer or is ending within 12 hours"
+ },
+ "25039": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
+ },
+ "25040": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
+ },
+ "25041": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s)."
+ },
+ "25042": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, free shipping must be provided."
+ },
+ "25043": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, returns must be accepted."
+ },
+ "25044": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, refund must be provided as Money Back."
+ },
+ "25045": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days."
+ },
+ "25046": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, seller must pay the cost for return shipping."
+ },
+ "25047": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition"
+ },
+ "25048": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition in this Category"
+ },
+ "25049": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller is not eligible to use Refurbished Item Condition for the selected Brand"
+ },
+ "25050": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title."
+ },
+ "25051": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle"
+ },
+ "25052": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing an item with Refurbished condition, at least {replaceable_value} images must be provided"
+ },
+ "25076": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{replaceable_value} ID(s) {replaceable_value} not found. Please use valid ID(s)."
+ },
+ "25077": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Duplicate Regulatory ID(s) {replaceable_value} sent in the request. Duplicate ID(s) have been ignored."
+ },
+ "25078": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Hazmat structure incorrect for {replaceable_value}."
+ },
+ "25079": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Repair score invalid. Repair score must be in the range from {replaceable_value} to {replaceable_value} with one decimal place."
+ },
+ "25080": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The value of the {0} field is invalid. Field must not exceed {replaceable_value} characters."
+ },
+ "25081": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Hazardous material information incomplete. Your listing must include hazardous statements."
+ },
+ "25083": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Energy efficiency image is missing. Image is required with image description."
+ },
+ "25084": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The listing must have both an energy efficiency label and a product information sheet."
+ },
+ "25086": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The URL provided must be an eBay Picture Service URL."
+ },
+ "25088": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The email address provided is formatted incorrectly."
+ },
+ "25089": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} global compliance policies allowed. Excess policies ignored."
+ },
+ "25090": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} compliance policies per region allowed. Excess policies ignored."
+ },
+ "25091": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than a total of {replaceable_value} compliance policies allowed. Excess policies ignored."
+ },
+ "25092": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} global takeback policy allowed."
+ },
+ "25093": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than {replaceable_value} takeback policy per region allowed. Excess policies ignored."
+ },
+ "25094": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No more than a total of {replaceable_value} takeback policies allowed."
+ },
+ "25095": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Region invalid for regional custom policy. Regions allowed are {replaceable_value}."
+ },
+ "25104": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Regulatory document ID(s) {replaceable_value} not found. Please use valid ID(s)."
+ },
+ "25106": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Regulatory document structure incorrect. Max allowed number of entries is {replaceable_value}."
+ },
+ "25107": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid document state for ID(s) {replaceable_value}. Documents must be in the SUBMITTED or ACCEPTED state."
+ },
+ "25108": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Product Safety structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
+ },
+ "25109": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Product safety information incomplete. Your listing must include pictograms or safety statements."
+ },
+ "25110": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Manufacturer address information is incomplete. When providing the address, please provide the street, city, postal code and country"
+ },
+ "25111": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Manufacturer information is incomplete. Please provide the company name."
+ },
+ "25112": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
+ },
+ "25113": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person address information is incomplete. When providing the address, please provide the street, city, postal code and country"
+ },
+ "25114": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Responsible Person information is incomplete. Please provide the company name."
+ },
+ "25115": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Either the Manufacturer or at least one of the Responsible Persons must be located in the EU."
+ },
+ "25116": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Please provide a minimum of {replaceable_value} and a maximum of {replaceable_value} types for a Responsible Person."
+ },
+ "25118": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller must provide at least one form of contact info for Manufacturer - either address, email, contact URL or phone."
+ },
+ "25119": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Seller must provide at least one form of contact info for Responsible Person - either address, email, contact URL or phone."
+ },
+ "25120": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing in {categoryName}, key information such as {fieldName} comes from eBayās catalog and should be left blank."
+ },
+ "25121": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "When listing in {categoryName}, sellers are required to adopt eBayās catalog data which will provide all the necessary details for the product."
+ },
+ "25122": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The contact URL is incorrectly formatted. Please update the formatting."
+ },
+ "25123": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This P&A listing has a non-compliant domestic return policy. Please update the return window to 30-days (or more) and/or update return shipping cost payer to Seller, and then make another call. Sellers using business policies must make the same changes to their return business policy and then make another call. To learn more, visit https://www.ebay.com/sellercenter/news/2025-june/parts-accessories-return-policy."
+ },
+ "25601": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid attribute. {fieldName}"
+ },
+ "25604": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25705": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system."
+ },
+ "25752": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "listingStartDate provided is invalid."
+ },
+ "25766": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The takeBackPolicyId field must be a long value type. Please correct the error."
+ },
+ "25767": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "The productCompliancePolicyId field must be a long value type. Please correct the error."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Any System error. {additionalInfo}"
+ },
+ "25025": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Concurrent access of Inventory or InventoryItemGroup. Please try again later"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/offer/{offerId}/withdraw": {
+ "post": {
+ "tags": [
+ "offer"
+ ],
+ "description": "This call is used to end a single-variation listing that is associated with the specified offer. This call is used in place of the deleteOffer call if the seller only wants to end the listing associated with the offer but does not want to delete the offer object. With this call, the offer object remains, but it goes into the unpublished state, and will require a publishOffer call to relist the offer.
To end a multiple-variation listing that is associated with an inventory item group, the withdrawOfferByInventoryItemGroup method can be used. This call only ends the multiple-variation listing associated with an inventory item group but does not delete the inventory item group object, nor does it delete any of the offers associated with the inventory item group, but instead all of these offers go into the unpublished state.",
+ "operationId": "withdrawOffer",
+ "parameters": [
+ {
+ "name": "offerId",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the offer that is to be withdrawn.
Use the getOffers method to retrieve offer IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WithdrawResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25402": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System warning. {additionalInfo}"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25002": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Any User error. {additionalInfo}"
+ },
+ "25713": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "This Offer is not available : {additionalInfo}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Any System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/offer/withdraw_by_inventory_item_group": {
+ "post": {
+ "tags": [
+ "offer"
+ ],
+ "description": "This call is used to end a multiple-variation eBay listing that is associated with the specified inventory item group. This call only ends multiple-variation eBay listing associated with the inventory item group but does not delete the inventory item group object. Similarly, this call also does not delete any of the offers associated with the inventory item group, but instead all of these offers go into the unpublished state. If the seller wanted to relist the multiple-variation eBay listing, they could use the publishOfferByInventoryItemGroup method.",
+ "operationId": "withdrawOfferByInventoryItemGroup",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The base request of the withdrawOfferByInventoryItemGroup call.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The base request of the withdrawOfferByInventoryItemGroup call.",
+ "$ref": "#/components/schemas/WithdrawByInventoryItemGroupRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25725": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "No offer found"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "Any System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/location/{merchantLocationKey}": {
+ "get": {
+ "tags": [
+ "location"
+ ],
+ "description": "This call retrieves all defined details of the inventory location that is specified by the merchantLocationKey path parameter.A successful call will return an HTTP status value of 200 OK.
",
+ "operationId": "getInventoryLocation",
+ "parameters": [
+ {
+ "name": "merchantLocationKey",
+ "in": "path",
+ "description": "This path parameter specifies the unique merchant-defined key (ID) for an inventory location that is being retrieved.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/InventoryLocationResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25804": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25805": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{fieldName} Not Found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "x-response-codes": {
- "errors": {
- "25096": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This listing is on hold due to a policy violation. You may revise it to resolve the situation. Please check your email for more information."
- },
- "25401": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Invalid listing format removed {additionalInfo}"
- },
- "25402": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System warning. {additionalInfo}"
- }
- }
- }
- },
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "A user error has occurred. {additionalInfo}"
- },
- "25003": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}"
- },
- "25004": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}"
- },
- "25005": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}"
- },
- "25006": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}"
- },
- "25007": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}"
- },
- "25008": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}"
- },
- "25009": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}"
- },
- "25011": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}"
- },
- "25012": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid inventory location. {additionalInfo}"
- },
- "25013": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
- },
- "25014": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}"
- },
- "25015": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}"
- },
- "25016": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The {fieldName} value is invalid. {additionalInfo}"
- },
- "25017": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
- },
- "25018": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
- },
- "25019": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
- },
- "25020": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}"
- },
- "25021": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}"
- },
- "25022": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25023": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid compatibility information. {additionalInfo}"
- },
- "25024": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid Best Offer information. {additionalInfo}"
- },
- "25026": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Selling limit exceeded. {additionalInfo}"
- },
- "25041": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s)."
- },
- "25042": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, free shipping must be provided."
- },
- "25043": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, returns must be accepted."
- },
- "25044": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, refund must be provided as Money Back."
- },
- "25045": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days."
- },
- "25046": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, seller must pay the cost for return shipping."
- },
- "25047": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition"
- },
- "25048": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition in this Category"
- },
- "25049": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition for the selected Brand"
- },
- "25050": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title."
- },
- "25051": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle"
- },
- "25052": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, at least {replaceable_value} images must be provided"
- },
- "25097": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This listing is on hold due to a policy violation, and revisions are not possible. Please check your email for more information."
- },
- "25098": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{replaceable_value} transaction is not possible as the parent listing is on-hold. Please check your email for further information. "
- },
- "25701": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "One or more of the supplied SKU(s) could not be found in the system."
- },
- "25702": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{skuValue} could not be found or is not available in the system."
- },
- "25703": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The following SKU is already a member of another group. SKU : {skuValue} groupId : {inventoryItemGroupKey}"
- },
- "25704": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The following SKU is already listed as a single SKU listing. SKU : {skuValue} Listing ID : {listingId}"
- },
- "25705": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}. {additionalInfo}"
- },
- "25756": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Auction format is not permitted with a SKU that is part of an InventoryItemGroup."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- },
- "25025": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "delete": {
- "tags": [
- "inventory_item_group"
- ],
- "description": "This call deletes the inventory item group for a given inventoryItemGroupKey value.",
- "operationId": "deleteInventoryItemGroup",
- "parameters": [
- {
- "name": "inventoryItemGroupKey",
- "in": "path",
- "description": "This path parameter specifies the unique identifier of the inventory item group being deleted. This value is assigned by the seller when an inventory item group is created.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25705": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}. {additionalInfo}"
- },
- "25710": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "We didn't find the resource/entity you are requesting. Please verify the request"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/bulk_migrate_listing": {
- "post": {
- "tags": [
- "listing"
- ],
- "description": "This call is used to convert existing eBay Listings to the corresponding Inventory API objects. If an eBay listing is successfully migrated to the Inventory API model, new Inventory Location, Inventory Item, and Offer objects are created. For a multiple-variation listing that is successfully migrated, in addition to the three new Inventory API objects just mentioned, an Inventory Item Group object will also be created. If the eBay listing is a motor vehicle part or accessory listing with a compatible vehicle list (ItemCompatibilityList container in Trading API's Add/Revise/Relist/Verify calls), a Product Compatibility object will be created.
Migration Requirements
To be eligible for migration, the active eBay listings must meet the following requirements:
Unsupported Listing Features
The following features are not yet available to be set or modified through the Inventory API, but they will remain on the active eBay listing, even after a successful migration to the Inventory model. The downside to this is that the seller will be completely blocked (in APIs or My eBay) from revising these features/settings once the migration takes place:- Any listing-level Buyer Requirements
- Listing enhancements like a bold listing title or Gallery Plus
Making the Call
In the request payload of the bulkMigrateListings call, the seller will pass in an array of one to five eBay listing IDs (aka Item IDs). To save time and hassle, that seller should do a pre-check on each listing to make sure those listings meet the requirements to be migrated to the new Inventory model. This method also requires the Content-Type request header. See the HTTP request headers for more information. There are no path or query parameters for this call.
Call Response
If an eBay listing is migrated successfully to the new Inventory model, the following will occur:- An Inventory Item object will be created for the item(s) in the listing, and this object will be accessible through the Inventory API
- An Offer object will be created for the listing, and this object will be accessible through the Inventory API
- An Inventory Location object will be created and associated with the Offer object, as an Inventory Location must be associated with a published Offer
The response payload of the Bulk Migrate Listings call will show the results of each listing migration. These results include an HTTP status code to indicate the success or failure of each listing migration, the SKU value associated with each item, and if the migration is successful, an Offer ID value. The SKU value will be used in the Inventory API to manage the Inventory Item object, and the Offer ID value will be used in the Inventory API to manage the Offer object. Errors and/or warnings containers will be returned for each listing where an error and/or warning occurred with the attempted migration.
If a multiple-variation listing is successfully migrated, along with the Offer and Inventory Location objects, an Inventory Item object will be created for each product variation within the listing, and an Inventory Item Group object will also be created, grouping those variations together in the Inventory API platform. For a motor vehicle part or accessory listing that has a specified list of compatible vehicles, in addition to the Inventory Item, Inventory Location, and Offer objects that are created, a Product Compatibility object will also be created in the Inventory API platform.",
- "operationId": "bulkMigrateListing",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "Details of the listings that needs to be migrated into Inventory",
- "content": {
- "application/json": {
- "schema": {
- "description": "Details of the listings that needs to be migrated into Inventory",
- "$ref": "#/components/schemas/BulkMigrateListing"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkMigrateListingResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi-Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25718": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Cannot migrate listing. {additionalInfo}"
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Any System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/listing/{listingId}/sku/{sku}/locations": {
- "get": {
- "tags": [
- "listing"
- ],
- "description": "This method allows sellers to retrieve the locations mapped to a specific SKU within a listing.
The listingId and sku of the listing are passed in as path parameters. This method only retrieves location mappings for a single SKU value; if a seller wishes to retrieve the location mappings for all items in a multiple-variation listing, this method must be called for each variation in the listing.
If there are fulfillment center locations mapped to the SKU, they will be returned in the locations array. If no locations are mapped to the SKU, status code 404 Not Found will be returned.",
- "operationId": "getSkuLocationMapping",
- "parameters": [
- {
- "name": "listingId",
- "in": "path",
- "description": "This path parameter specifies the unique identifier of the listing that the SKU belongs to for which all mapped locations will be retrieved.
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all listing IDs for all active listings.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "sku",
- "in": "path",
- "description": "This path parameter specifies the seller-defined SKU value of the item/variation for which location mappings will be retrieved. This SKU value must be defined in the listing specified in listingId parameter
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all SKUs for all active listings.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/LocationMapping"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Any User error. {additionalInfo}"
- },
- "25904": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid listing ID or the listing does not belong to the seller."
- },
- "25905": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid SKU value or the SKU value is not defined in the listing."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Any System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory",
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly"
- ]
- }
- ]
- },
- "put": {
- "tags": [
- "listing"
- ],
- "description": "This method allows sellers to map multiple fulfillment center locations to single-SKU listing, or to a single SKU within a multiple-variation listing. This allows eBay to leverage the location metadata associated with a sellerās fulfillment centers to calculate more accurate estimated delivery dates on their listing.
Note: While location mappings can be created for listings on any eBay marketplace, the improved delivery date estimate feature is currently only supported for US-based fulfillment centers shipping domestically within the US.
The listing for which the locations will be mapped is specified through the listingId and sku values associated with the item. Note that only a single SKU value can be identified; if the seller wishes to map locations to multiple/all SKU values in a multiple-variation listing, this method must be called for each of those SKUs within the listing.
Note: Sellers should keep track of listingId/sku pairs that have been used for location mapping, as there is no programmatic way to retrieve or delete these pairs at this time.
In the case of replacing/updating existing location mappings, this method will do a complete replacement of the location mappings associated with a SKU. This means that each existing location mappings that the seller wants to continue to associate with the SKU are required in the update call, regardless of if they are affected by the update.
This method is only supported for inventory locations that have FULFILLMENT_CENTER as one of their locationTypes. For more information on fulfillment center locations, see Create a fulfillment center location.
For more information on location mapping features, see Multi-warehouse program in the Selling Integration Guide.
Note: Only listings with SKU values are supported. Sellers using listings creating through the Trading API can add a SKU value to their single variation listing through the Item.SKU field during listing creation or by using the ReviseItem family of calls.",
- "operationId": "createOrReplaceSkuLocationMapping",
- "parameters": [
- {
- "name": "listingId",
- "in": "path",
- "description": "This path parameter specifies the unique identifier of the listing for which multiple fulfillment center locations will be mapped to a SKU within that listing.
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all listing IDs for all active listings.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "sku",
- "in": "path",
- "description": "This path parameter specifies the seller-defined SKU value of the item/variation for which multiple fulfillment center locations will be mapped. This SKU value must be defined in the listing specified in listingId parameter.
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all listing IDs for all active listings.
Note: SKU values can be updated by a seller at any time. If a seller updates a SKU value that is being used for location mapping, this change will not be reflected until the mapping is updated through the createOrReplaceSkuLocationMapping method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/LocationMapping"
- }
- }
- },
- "required": true
- },
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Any User error. {additionalInfo}"
- },
- "25900": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "One or more inventory locations could not be found for the seller."
- },
- "25901": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Missing a location. Please specify one or more inventory locations."
- },
- "25902": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "One or more duplicate inventory locations were specified. Unique inventory locations must be used."
- },
- "25904": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid listing ID or the listing does not belong to the seller."
- },
- "25905": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid SKU value or the SKU value is not defined in the listing."
- },
- "25906": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The provided inventory location must be a Fulfillment Center. Please use a Fulfillment Center location or use updateInventoryLocation to change location type to FULFILLMENT_CENTER."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Any System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "delete": {
- "tags": [
- "listing"
- ],
- "description": "This method allows sellers to remove all location mappings associated with a specific SKU within a listing.
The listingId and sku of the listing are passed in as path parameters.
Important! To remove all location mappings from a multiple-variation listing, this method must be used for each individual SKU in the listing.
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all listing IDs for all active listings.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "sku",
- "in": "path",
- "description": "This path parameter specifies the seller-defined SKU value of the item/variation for which location mappings will be removed. This SKU value must be defined in the listing specified in listingId parameter
Use the getOffers method of the Inventory API or the GetMyEbaySelling method of the Trading API to retrieve all SKUs for all active listings.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Any User error. {additionalInfo}"
- },
- "25904": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid listing ID or the listing does not belong to the seller."
- },
- "25905": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid SKU value or the SKU value is not defined in the listing."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Any System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/bulk_create_offer": {
- "post": {
- "tags": [
- "offer"
- ],
- "description": "This call creates multiple offers (up to 25) for specific inventory items on a specific eBay marketplace. Although it is not a requirement for the seller to create complete offers (with all necessary details) right from the start, eBay recommends that the seller provide all necessary details with this call since there is currently no bulk operation available to update multiple offers with one call. The following fields are always required in the request payload: sku, marketplaceId, and (listing) format.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Offer fields for a list of fields required to publish an offer.
Other information that will be required before a offer can be published are highlighted below: - Inventory location
- Offer price
- Available quantity
- eBay listing category
- Referenced listing policy profiles to set payment, return, and fulfillment values/settings
Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to true if omitted.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.
If the call is successful, unique offerId values are returned in the response for each successfully created offer. The offerId value will be required for many other offer-related calls. Note that this call only stages an offer for publishing. The seller must run either the publishOffer, bulkPublishOffer, or publishOfferByInventoryItemGroup call to convert offer(s) into an active single- or multiple-variation listing.
For those who prefer to create a single offer per call, the createOffer method can be used instead.
",
- "operationId": "bulkCreateOffer",
- "parameters": [
- {
- "name": "Content-Language",
- "in": "header",
- "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "Details of the offer for the channel",
- "content": {
- "application/json": {
- "schema": {
- "description": "Details of the offer for the channel",
- "$ref": "#/components/schemas/BulkEbayOfferDetailsWithKeys"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkOfferResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi-Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25702": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "SKU {additionalInfo} is not available in the system"
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid request. Invalid value for field {additionalInfo}"
- },
- "25729": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The combination of SKU, marketplaceId and format should be unique."
- },
- "25730": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The number of offers in the request cannot exceed {additionalInfo}"
- },
- "25735": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid SKU, marketplaceId or format."
- },
- "25752": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate provided is invalid."
- },
- "25755": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingDuration is required for auction offer."
- },
- "25756": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Auction format is not permitted with a SKU that is part of an InventoryItemGroup."
- },
- "25757": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "auctionStartPrice is required for auction offer."
- },
- "25758": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "auctionStartPrice and auctionReservePrice are not supported for fixed price offer."
- },
- "25761": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Discount pricing is not applicable for auction offer."
- },
- "25762": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "availableQuantity is not applicable for auction offer."
- },
- "25763": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "quantityLimitPerBuyer is not applicable for auction offer."
- },
- "25764": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "eBayPlusIfEligible is not applicable for auction offer."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Any System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/bulk_publish_offer": {
- "post": {
- "tags": [
- "offer"
- ],
- "description": "Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call is used to convert unpublished offers (up to 25) into published offers, or live eBay listings. The unique identifier (offerId) of each offer to publish is passed into the request payload. It is possible that some unpublished offers will be successfully created into eBay listings, but others may fail. The response payload will show the results for each offerId value that is passed into the request payload. The errors and warnings containers will be returned for an offer that had one or more issues being published.
Important!Publish offer note: Fields may be optional or conditionally required when calling the create or update methods, but become required when publishing the offer to create active listings. For this method, see Offer fields for a list of fields required to publish an offer.
For those who prefer to publish one offer per call, the publishOffer method can be used instead. In the case of a multiple-variation listing, the publishOfferByInventoryItemGroup call should be used instead, as this call will convert all unpublished offers associated with an inventory item group into a multiple-variation listing.",
- "operationId": "bulkPublishOffer",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "The base request of the bulkPublishOffer method.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The base request of the bulkPublishOffer method.",
- "$ref": "#/components/schemas/BulkOffer"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkPublishResponse"
- }
- }
+ "post": {
+ "tags": [
+ "location"
+ ],
+ "description": "Use this call to create a new inventory location. In order to create and publish an offer (and create an eBay listing), a seller must have at least one location, as every offer must be associated with at least one location.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Location fields for a list of fields required to publish an offer.
Upon first creating an inventory location, only a seller-defined location identifier and a physical location is required, and once set, these values can not be changed. The unique identifier value (merchantLocationKey) is passed in at the end of the call URI. This merchantLocationKey value will be used in other Inventory Location calls to identify the location to perform an action against.
When creating an inventory location, the locationTypes can be specified to define the function of a location. At this time, the following locationTypes are supported:
- Fulfillment center locations are used by sellers selling products through the Multi-warehouse program to get improved estimated delivery dates on their listings. A full address is required when creating a fulfillment center location, as well as the fulfillmentCenterSpecifications of the location. For more information on using the fulfillment center location type to get improved delivery dates, see Multi-warehouse program.
- Warehouse locations are used for traditional shipping. A full street address is not needed, but the postalCode and country OR city, stateOrProvince, and country of the location must be provided.
- Store locations are generally used by merchants selling product through the In-Store Pickup program. A full address is required when creating a store location.
Note that all inventory locations are \"enabled\" by default when they are created, and you must specifically disable them (by passing in a value of DISABLED in the merchantLocationStatus field) if you want them to be set to the disabled state. The seller's inventory cannot be loaded to inventory locations in the disabled state.
Unless one or more errors and/or warnings occur with the call, there is no response payload for this call. A successful call will return an HTTP status value of 204 No Content.
",
+ "operationId": "createInventoryLocation",
+ "parameters": [
+ {
+ "name": "merchantLocationKey",
+ "in": "path",
+ "description": "This path parameter specifies the unique, seller-defined key (ID) for an inventory location.
Max length: 36",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Inventory Location details",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Inventory Location details",
+ "$ref": "#/components/schemas/InventoryLocationFull"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25800": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid {fieldName}."
+ },
+ "25801": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Missing field {fieldName}."
+ },
+ "25802": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25803": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{fieldName} already exists."
+ },
+ "25804": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Location Already Exists",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
},
- "x-response-codes": {
- "errors": {
- "25028": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not applicable and has been dropped"
- },
- "25030": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not applicable for the condition and has been dropped"
- },
- "25033": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Duplicate policy IDs found"
- },
- "25037": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Item level Eco Participation Fee will be ignored"
- },
- "25401": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Invalid listing options removed. {additionalInfo}"
- },
- "25402": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System warning. {additionalInfo}"
- },
- "25753": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
- }
- }
- }
- },
- "207": {
- "description": "Multi-Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Any User error. {additionalInfo}"
- },
- "25003": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid price. {additionalInfo}"
- },
- "25004": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid quantity. {additionalInfo}"
- },
- "25005": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid category. {additionalInfo}"
- },
- "25006": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid listing option. {additionalInfo}"
- },
- "25007": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid Shipping policy information. {additionalInfo}"
- },
- "25008": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid Payment policy information. {additionalInfo}"
- },
- "25009": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid Return policy information. {additionalInfo}"
- },
- "25011": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid tax information. {additionalInfo}"
- },
- "25012": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid location. {additionalInfo}"
- },
- "25013": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
- },
- "25014": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid pictures. {additionalInfo}"
- },
- "25015": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid picture URL. {additionalInfo}"
- },
- "25016": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid {fieldName}. {additionalInfo}"
- },
- "25017": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
- },
- "25018": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
- },
- "25019": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
- },
- "25020": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid package details. {additionalInfo}"
- },
- "25021": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid condition information. {additionalInfo}"
- },
- "25022": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25023": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid compatibility information. {additionalInfo}"
- },
- "25026": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Selling limits exceeded. {additionalInfo}"
- },
- "25029": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is required for this category."
- },
- "25031": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not valid and needs to be a number between {min} and {max}"
- },
- "25032": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not valid"
- },
- "25034": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Only {max value} policies can be specified"
- },
- "25035": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The specified policy is not found for the market place"
- },
- "25036": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The policy(ies) {PolicyId} is not of type {PolicyEnum}"
- },
- "25038": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer or is ending within 12 hours"
- },
- "25039": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
- },
- "25040": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
- },
- "25041": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s)."
- },
- "25042": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, free shipping must be provided."
- },
- "25043": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, returns must be accepted."
- },
- "25044": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, refund must be provided as Money Back."
- },
- "25045": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days."
- },
- "25046": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, seller must pay the cost for return shipping."
- },
- "25047": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition"
- },
- "25048": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition in this Category"
- },
- "25049": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition for the selected Brand"
- },
- "25050": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title."
- },
- "25051": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle"
- },
- "25052": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, at least {replaceable_value} images must be provided"
- },
- "25076": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{replaceable_value} ID(s) {replaceable_value} not found. Please use valid ID(s)."
- },
- "25077": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Duplicate Regulatory ID(s) {replaceable_value} sent in the request. Duplicate ID(s) have been ignored."
- },
- "25078": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Hazmat structure incorrect for {replaceable_value}."
- },
- "25079": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Repair score invalid. Repair score must be in the range from {replaceable_value} to {replaceable_value} with one decimal place."
- },
- "25080": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The value of the {0} field is invalid. Field must not exceed {replaceable_value} characters."
- },
- "25081": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Hazardous material information incomplete. Your listing must include hazardous statements."
- },
- "25083": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Energy efficiency image is missing. Image is required with image description."
- },
- "25084": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The listing must have both an energy efficiency label and a product information sheet."
- },
- "25086": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The URL provided must be an eBay Picture Service URL."
- },
- "25088": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The email address provided is formatted incorrectly."
- },
- "25089": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} global compliance policies allowed. Excess policies ignored."
- },
- "25090": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} compliance policies per region allowed. Excess policies ignored."
- },
- "25091": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than a total of {replaceable_value} compliance policies allowed. Excess policies ignored."
- },
- "25092": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} global takeback policy allowed."
- },
- "25093": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} takeback policy per region allowed. Excess policies ignored."
- },
- "25094": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than a total of {replaceable_value} takeback policies allowed."
- },
- "25095": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Region invalid for regional custom policy. Regions allowed are {replaceable_value}."
- },
- "25104": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Regulatory document ID(s) {replaceable_value} not found. Please use valid ID(s)."
- },
- "25106": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Regulatory document structure incorrect. Max allowed number of entries is {replaceable_value}."
- },
- "25107": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid document state for ID(s) {replaceable_value}. Documents must be in the SUBMITTED or ACCEPTED state."
- },
- "25108": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Product Safety structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
- },
- "25109": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Product Safety information incomplete. Your listing must include product safety pictograms & statements."
- },
- "25110": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Manufacturer address information is incomplete. When providing the address, please provide the street, city, postal code and country"
- },
- "25111": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Manufacturer information is incomplete. Please provide the company name."
- },
- "25112": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
- },
- "25113": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person address information is incomplete. When providing the address, please provide the street, city, postal code and country"
- },
- "25114": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person information is incomplete. Please provide the company name."
- },
- "25115": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Either the Manufacturer or at least one of the Responsible Persons must be located in the EU."
- },
- "25116": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Please provide a minimum of {replaceable_value} and a maximum of {replaceable_value} types for a Responsible Person."
- },
- "25118": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller must provide at least one form of contact info for Manufacturer - either phone, email or address."
- },
- "25119": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller must provide at least one form of contact info for Responsible Person - either phone, email or address."
- },
- "25601": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25604": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid offerId"
- },
- "25713": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This Offer is not available : {additionalInfo}."
- },
- "25730": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The number of offers in the request cannot exceed {additionalInfo}."
- },
- "25731": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "OfferId should be unique in the request."
- },
- "25732": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Offers associated with SKUs that are part of a variation group cannot be published using this endpoint."
- },
- "25752": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate provided is invalid."
- },
- "25760": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "shipToLocationAvailability quantity insufficient to create auction listings."
- },
- "25766": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The takeBackPolicyId field must be a long value type. Please correct the error."
- },
- "25767": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The productCompliancePolicyId field must be a long value type. Please correct the error."
- }
- }
+ "delete": {
+ "tags": [
+ "location"
+ ],
+ "description": "This call deletes the inventory location that is specified in the merchantLocationKey path parameter. Note that deleting a location will not affect any active eBay listings associated with the deleted location, but the seller will not be able modify the offers associated with the location once it is deleted.
Note: Deletion is not currently supported for fulfillment center locations, as location mappings will still be retained despite the location being deleted. Instead, fulfillment center locations should be disabled using the disableInventoryLocation method.Unless one or more errors and/or warnings occur with the call, there is no response payload for this call. A successful call will return an HTTP status value of 200 OK.
",
+ "operationId": "deleteInventoryLocation",
+ "parameters": [
+ {
+ "name": "merchantLocationKey",
+ "in": "path",
+ "description": "This path parameter specifies the unique merchant-defined key (ID) for the inventory location that is to be deleted.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25802": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25804": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25805": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{fieldName} Not Found."
+ },
+ "25806": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Deletion is not allowed when the location type of an inventory location has been set to fulfillment center. However, you may disable it."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/location/{merchantLocationKey}/disable": {
+ "post": {
+ "tags": [
+ "location"
+ ],
+ "description": "This call disables the inventory location that is specified in the merchantLocationKey path parameter. Sellers can not load/modify inventory to disabled locations. Note that disabling a location will not affect any active eBay listings associated with the disabled location, but the seller will not be able modify the offers associated with a disabled location.
A successful call will return an HTTP status value of 200 OK.
",
+ "operationId": "disableInventoryLocation",
+ "parameters": [
+ {
+ "name": "merchantLocationKey",
+ "in": "path",
+ "description": "This path parameter specifies the unique merchant-defined key (ID) for an inventory location that is to be disabled.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25802": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25804": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25805": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{fieldName} Not Found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/location/{merchantLocationKey}/enable": {
+ "post": {
+ "tags": [
+ "location"
+ ],
+ "description": "This call enables a disabled inventory location that is specified in the merchantLocationKey path parameter. Once a disabled location is enabled, sellers can start loading/modifying inventory to that location.
A successful call will return an HTTP status value of 200 OK.
",
+ "operationId": "enableInventoryLocation",
+ "parameters": [
+ {
+ "name": "merchantLocationKey",
+ "in": "path",
+ "description": "This path parameter specifies unique merchant-defined key (ID) for a disabled inventory location that is to be enabled.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25802": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25804": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25805": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{fieldName} Not Found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/location": {
+ "get": {
+ "tags": [
+ "location"
+ ],
+ "description": "This call retrieves all defined details for every inventory location associated with the seller's account. There are no required parameters for this call and no request payload. However, there are two optional query parameters, limit and offset. The limit query parameter sets the maximum number of locations returned on one page of data, and the offset query parameter specifies the page of data to return. These query parameters are discussed more in the URI parameters table below. The authorization HTTP header is the only required request header for this call.
A successful call will return an HTTP status value of 200 OK.
",
+ "operationId": "getInventoryLocations",
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The value passed in this query parameter sets the maximum number of records to return per page of data. Although this field is a string, the value passed in this field should be a positive integer value. If this query parameter is not set, up to 100 records will be returned on each page of results.
Min: 1",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "Specifies the number of locations to skip in the result set before returning the first location in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/LocationResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
+ }
+ },
+ "/location/{merchantLocationKey}/update_location_details": {
+ "post": {
+ "tags": [
+ "location"
+ ],
+ "description": "Use this call to update location details for an existing inventory location. Specify the inventory location you want to update using the merchantLocationKey path parameter.
You can update the following text-based fields: name, phone, timeZoneId, geoCoordinates, fulfillmentCenterSpecifications, locationTypes, locationWebUrl, locationInstructions and locationAdditionalInformation any number of times for any location type.
For warehouse and store inventory locations, address fields can be updated any number of times. Address fields cannot be updated for fulfillment center locations. However, if any address fields were omitted during the createInventoryLocation call, they can be added through this method.
Note: When updating a warehouse location to a fulfillment center, sellers can update any of the address fields a single time during the same call used to make this update. After this, they can no longer be updated.For store locations, the operating hours and/or the special hours can also be updated.
Whatever text is passed in for these fields in an updateInventoryLocation call will replace the current text strings defined for these fields.
Unless one or more errors and/or warnings occurs with the call, there is no response payload for this call. A successful call will return an HTTP status value of 204 No Content.
",
+ "operationId": "updateInventoryLocation",
+ "parameters": [
+ {
+ "name": "merchantLocationKey",
+ "in": "path",
+ "description": "This path parameter specifies the unique merchant-defined key (ID) for an inventory location that is to be updated.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The inventory location details to be updated.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The inventory location details to be updated.",
+ "$ref": "#/components/schemas/InventoryLocation"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25800": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Invalid {fieldName}."
+ },
+ "25801": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Missing field {fieldName}."
+ },
+ "25802": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25803": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{fieldName} already exists."
+ },
+ "25804": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "Input error. {additionalInfo}"
+ },
+ "25805": {
+ "domain": "API_INVENTORY",
+ "category": "REQUEST",
+ "description": "{fieldName} Not Found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "25001": {
+ "domain": "API_INVENTORY",
+ "category": "APPLICATION",
+ "description": "System error. {additionalInfo}"
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
}
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Any System error. {additionalInfo}"
- },
- "25025": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Concurrent access of Inventory or InventoryItemGroup. Please try again later"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
+ }
},
- "/offer": {
- "get": {
- "tags": [
- "offer"
- ],
- "description": "This call retrieves all existing offers for the specified SKU value. The seller has the option of limiting the offers that are retrieved to a specific eBay marketplace, or to a listing format.
Note: At this time, the same SKU value can not be offered across multiple eBay marketplaces, so the marketplace_id query parameter currently does not have any practical use for this call.
Note: The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, getOffers will return two offers. Otherwise, only one offer will be returned.
The authorization header is the only required HTTP header for this call. See the HTTP request headers section for more information.",
- "operationId": "getOffers",
- "parameters": [
- {
- "name": "format",
- "in": "query",
- "description": "This enumeration value sets the listing format for the offers being retrieved. This query parameter will be passed in if the seller only wants to see offers in a specified listing format, such as FIXED_PRICE.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "limit",
- "in": "query",
- "description": "The value passed in this query parameter sets the maximum number of records to return per page of data. Although this field is a string, the value passed in this field should be a positive integer value. If this query parameter is not set, up to 100 records will be returned on each page of results.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "marketplace_id",
- "in": "query",
- "description": "The unique identifier of the eBay marketplace. This query parameter will be passed in if the seller only wants to see the product's offers on a specific eBay marketplace.
Note: At this time, the same SKU value can not be offered across multiple eBay marketplaces, so the marketplace_id query parameter currently does not have any practical use for this call.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "The value passed in this query parameter sets the page number to retrieve. Although this field is a string, the value passed in this field should be a integer value equal to or greater than 0. The first page of records has a value of 0, the second page of records has a value of 1, and so on. If this query parameter is not set, its value defaults to 0, and the first page of records is returned.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "sku",
- "in": "query",
- "description": "The seller-defined SKU value is passed in as a query parameter. All offers associated with this product are returned in the response.
Note: The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, getOffers will return two offers. Otherwise, only one offer will be returned.
Use the getInventoryItems method to retrieve SKU values.
Max length: 50.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Offers"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25706": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "You have provided invalid pagination values. {additionalInfo}."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}. {additionalInfo}"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "post": {
- "tags": [
- "offer"
- ],
- "description": "This call creates an offer for a specific inventory item on a specific eBay marketplace. It is up to the sellers whether they want to create a complete offer (with all necessary details) right from the start, or sellers can provide only some information with the initial createOffer call, and then make one or more subsequent updateOffer calls to complete the offer and prepare to publish the offer. Upon first creating an offer, the following fields are required in the request payload: sku, marketplaceId, and (listing) format.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Offer fields for a list of fields required to publish an offer.
Other information that will be required before an offer can be published are highlighted below. These settings are either set with createOffer, or they can be set with a subsequent updateOffer call: - Inventory location
- Offer price
- Available quantity
- eBay listing category
- Referenced listing policy profiles to set payment, return, and fulfillment values/settings
Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to true if omitted.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.If the call is successful, a unique offerId value is returned in the response. This value will be required for many other offer-related calls. Note that this call only stages an offer for publishing. The seller must run the publishOffer call to convert the offer to an active eBay listing.
For those who prefer to create multiple offers (up to 25 at a time) with one call, the bulkCreateOffer method can be used.
",
- "operationId": "createOffer",
- "parameters": [
- {
- "name": "Content-Language",
- "in": "header",
- "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "Details of the offer for the channel",
- "content": {
- "application/json": {
- "schema": {
- "description": "Details of the offer for the channel",
- "$ref": "#/components/schemas/EbayOfferDetailsWithKeys"
- }
- }
- },
- "required": true
- },
- "responses": {
- "201": {
- "description": "Created",
- "headers": {
- "Content-Language": {
- "schema": {
- "type": "string",
- "description": "This response header sets the natural language that will be provided in the field values of the response payload."
- }
- }
+ "components": {
+ "schemas": {
+ "Address": {
+ "type": "object",
+ "properties": {
+ "addressLine1": {
+ "type": "string",
+ "description": "The first line of a street address. This field is required for store and fulfillment center locations. A street address is not required for warehouse locations.
This field will be returned if defined for an inventory location.
Max length: 128"
+ },
+ "addressLine2": {
+ "type": "string",
+ "description": "The second line of a street address. This field can be used for additional address information, such as a suite or apartment number.
This field will be returned if defined for an inventory location.
Max length: 128"
+ },
+ "city": {
+ "type": "string",
+ "description": "The city in which the inventory location resides. This field is required for store and fulfillment center locations. For warehouse locations, this field is conditionally required as part of a city and stateOrProvince pair if a postalCode is not provided. If a postalCode is provided, the city is derived from the provided postal code and this field is technically optional.
This field is returned if defined for an inventory location.
Max length: 128"
+ },
+ "country": {
+ "type": "string",
+ "description": "The country in which the address resides, represented as two-letter ISO 3166 country code. For example, US represents the United States, and DE represents Germany. For implementation help, refer to eBay API documentation"
+ },
+ "county": {
+ "type": "string",
+ "description": "The county in which the address resides.
This field is returned if defined for an inventory location."
+ },
+ "postalCode": {
+ "type": "string",
+ "description": "The postal/zip code of the address. eBay uses postal codes to surface In-Store Pickup items within the vicinity of a buyer's location, and it also uses postal codes (origin and destination) to estimate shipping costs when the seller uses calculated shipping. This field is required for store and fulfillment center locations.
For warehouse locations, this field is conditionally required if a city and stateOrProvince pair is not provided.
Note: For warehouse locations, city and stateOrProvince pair can be used instead of a postalCode value, and then the postal code is just derived from the city and state/province.
This field is returned if defined for an inventory location.
Max length: 16"
+ },
+ "stateOrProvince": {
+ "type": "string",
+ "description": "The state/province in which the inventory location resides. This field is required for store and fulfillment center locations. For warehouse locations, this field is conditionally required as part of a city and stateOrProvince pair if a postalCode is not provided. If a postalCode is provided, the state or province is derived from the provided zip code and this field is technically optional.
Max length: 128"
+ }
+ },
+ "description": "This type is used to define the physical address of an inventory location."
},
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/OfferResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25702": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{skuValue} could not be found or is not available in the system."
- },
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}. {additionalInfo}"
- },
- "25752": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate provided is invalid."
- },
- "25755": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingDuration is required for auction offer."
- },
- "25756": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Auction format is not permitted with a SKU that is part of an InventoryItemGroup."
- },
- "25757": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "auctionStartPrice is required for auction offer."
- },
- "25758": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "auctionStartPrice and auctionReservePrice are not supported for fixed price offer."
- },
- "25761": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Discount pricing is not applicable for auction offer."
- },
- "25762": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "availableQuantity is not applicable for auction offer."
- },
- "25763": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "quantityLimitPerBuyer is not applicable for auction offer."
- },
- "25764": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "eBayPlusIfEligible is not applicable for auction offer."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/offer/{offerId}": {
- "get": {
- "tags": [
- "offer"
- ],
- "description": "This call retrieves a specific published or unpublished offer. The unique identifier of the offer (offerId) is passed in at the end of the call URI.The authorization header is the only required HTTP header for this call. See the HTTP request headers section for more information.
",
- "operationId": "getOffer",
- "parameters": [
- {
- "name": "offerId",
- "in": "path",
- "description": "This path parameter specifies the unique identifier of the offer that is to be retrieved.
Use the getOffers method to retrieve offer IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/EbayOfferDetailsWithAll"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}. {additionalInfo}"
- },
- "25713": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This Offer is not available : {additionalInfo}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "put": {
- "tags": [
- "offer"
- ],
- "description": "This call updates an existing offer. An existing offer may be in published state (active eBay listing), or in an unpublished state and yet to be published with the publishOffer call. The unique identifier (offerId) for the offer to update is passed in at the end of the call URI.
The updateOffer call does a complete replacement of the existing offer object, so all fields that make up the current offer object are required, regardless of whether their values changed.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Offer fields for a list of fields required to publish an offer.
Other information that is required before an unpublished offer can be published or before a published offer can be revised include: - Inventory location
- Offer price
- Available quantity
- eBay listing category
- Referenced listing policy profiles to set payment, return, and fulfillment values/settings
Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to true if omitted from both the updateOffer and the createOffer calls. If a value is specified in the updateOffer call, this value will be used.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
For published offers, the listingDescription field is also required to update the offer/eBay listing. For unpublished offers, this field is not necessarily required unless it is already set for the unpublished offer.
",
- "operationId": "updateOffer",
- "parameters": [
- {
- "name": "Content-Language",
- "in": "header",
- "description": "This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.
For more information on the Content-Language header, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offerId",
- "in": "path",
- "description": "This path parameter specifies the unique identifier of the offer being updated.
Use the getOffers method to retrieve offer IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "Details of the offer for the channel",
- "content": {
- "application/json": {
- "schema": {
- "description": "Details of the offer for the channel",
- "$ref": "#/components/schemas/EbayOfferDetailsWithId"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "headers": {
- "Content-Language": {
- "schema": {
- "type": "string",
- "description": "This response header sets the natural language that will be provided in the field values of the response payload."
- }
- }
+ "Amount": {
+ "type": "object",
+ "properties": {
+ "currency": {
+ "type": "string",
+ "description": "A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices.
See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values."
+ },
+ "value": {
+ "type": "string",
+ "description": "A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices."
+ }
+ },
+ "description": "This type is used to express a dollar value and the applicable currency."
},
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/OfferResponse"
- }
- }
+ "Availability": {
+ "type": "object",
+ "properties": {
+ "pickupAtLocationAvailability": {
+ "type": "array",
+ "description": "This container consists of an array of one or more of the merchant's physical store locations where the inventory item is available for In-Store Pickup orders. The merchant's location, the quantity available, and the fulfillment time (how soon the item will be ready for pickup after the order takes place) are all in this container. In-Store Pickup is only available to large merchants selling on the US, UK, Germany, and Australia sites.",
+ "items": {
+ "$ref": "#/components/schemas/PickupAtLocationAvailability"
+ }
+ },
+ "shipToLocationAvailability": {
+ "description": "This container specifies the quantity of the inventory item that are available for purchase across one or more eBay marketplaces.",
+ "$ref": "#/components/schemas/ShipToLocationAvailability"
+ }
+ },
+ "description": "This type is used to specify the quantity of the inventory item that is available for purchase if the item will be shipped to the buyer, and the quantity of the inventory item that is available for In-Store Pickup at one or more of the merchant's physical stores. In-Store Pickup is only available to large merchants selling on the US, UK, Germany, and Australia sites."
},
- "x-response-codes": {
- "errors": {
- "25028": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not applicable and has been dropped"
- },
- "25030": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not applicable for the condition and has been dropped"
- },
- "25033": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Duplicate policy IDs found"
- },
- "25037": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Item level Eco Participation Fee will be ignored"
- },
- "25401": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Invalid listing options removed. {additionalInfo}"
- },
- "25402": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System warning. {additionalInfo}"
- },
- "25753": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
- }
- }
- }
- },
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "A user error has occurred. {additionalInfo}"
- },
- "25003": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}"
- },
- "25004": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}"
- },
- "25005": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}"
- },
- "25006": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}"
- },
- "25007": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}"
- },
- "25008": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}"
- },
- "25009": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}"
- },
- "25011": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}"
- },
- "25012": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid inventory location. {additionalInfo}"
- },
- "25013": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
- },
- "25014": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}"
- },
- "25015": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}"
- },
- "25016": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The {fieldName} value is invalid. {additionalInfo}"
- },
- "25017": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
- },
- "25018": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
- },
- "25019": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
- },
- "25020": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}"
- },
- "25021": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}"
- },
- "25022": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25023": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid compatibility information. {additionalInfo}"
- },
- "25026": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Selling limit exceeded. {additionalInfo}"
- },
- "25029": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is required for this category."
- },
- "25031": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not valid and needs to be a number between {min} and {max}"
- },
- "25032": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not valid"
- },
- "25034": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Only {max value} policies can be specified"
- },
- "25035": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The specified policy is not found for the market place"
- },
- "25036": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The policy(ies) {PolicyId} is not of type {PolicyEnum}"
- },
- "25038": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer or is ending within 12 hours"
- },
- "25039": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
- },
- "25040": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
- },
- "25076": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{replaceable_value} ID(s) {replaceable_value} not found. Please use valid ID(s)."
- },
- "25077": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Duplicate Regulatory ID(s) {replaceable_value} sent in the request. Duplicate ID(s) have been ignored."
- },
- "25078": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Hazmat structure incorrect for {replaceable_value}."
- },
- "25079": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Repair score invalid. Repair score must be in the range from {replaceable_value} to {replaceable_value} with one decimal place."
- },
- "25080": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The value of the {0} field is invalid. Field must not exceed {replaceable_value} characters."
- },
- "25081": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Hazardous material information incomplete. Your listing must include hazardous statements."
- },
- "25083": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Energy efficiency image is missing. Image is required with image description."
- },
- "25084": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The listing must have both an energy efficiency label and a product information sheet."
- },
- "25086": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The URL provided must be an eBay Picture Service URL."
- },
- "25088": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The email address provided is formatted incorrectly."
- },
- "25089": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} global compliance policies allowed. Excess policies ignored."
- },
- "25090": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} compliance policies per region allowed. Excess policies ignored."
- },
- "25091": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than a total of {replaceable_value} compliance policies allowed. Excess policies ignored."
- },
- "25092": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} global takeback policy allowed."
- },
- "25093": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} takeback policy per region allowed. Excess policies ignored."
- },
- "25094": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than a total of {replaceable_value} takeback policies allowed."
- },
- "25095": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Region invalid for regional custom policy. Regions allowed are {replaceable_value}."
- },
- "25104": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Regulatory document ID(s) {replaceable_value} not found. Please use valid ID(s)."
- },
- "25106": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Regulatory document structure incorrect. Max allowed number of entries is {replaceable_value}."
- },
- "25107": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid document state for ID(s) {replaceable_value}. Documents must be in the SUBMITTED or ACCEPTED state."
- },
- "25108": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Product Safety structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
- },
- "25109": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Product Safety information incomplete. Your listing must include product safety pictograms & statements."
- },
- "25110": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Manufacturer address information is incomplete. When providing the address, please provide the street, city, postal code and country"
- },
- "25111": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Manufacturer information is incomplete. Please provide the company name."
- },
- "25112": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
- },
- "25113": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person address information is incomplete. When providing the address, please provide the street, city, postal code and country"
- },
- "25114": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person information is incomplete. Please provide the company name."
- },
- "25115": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Either the Manufacturer or at least one of the Responsible Persons must be located in the EU."
- },
- "25116": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Please provide a minimum of {replaceable_value} and a maximum of {replaceable_value} types for a Responsible Person."
- },
- "25118": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller must provide at least one form of contact info for Manufacturer - either phone, email or address."
- },
- "25119": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller must provide at least one form of contact info for Responsible Person - either phone, email or address."
- },
- "25601": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25604": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25710": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "We didn't find the resource/entity you are requesting. Please verify the request"
- },
- "25713": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This Offer is not available : {additionalInfo}."
- },
- "25752": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate provided is invalid."
- },
- "25756": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Auction format is not permitted with a SKU that is part of an InventoryItemGroup."
- },
- "25757": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "auctionStartPrice is required for auction offer."
- },
- "25758": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "auctionStartPrice and auctionReservePrice are not supported for fixed price offer."
- },
- "25761": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Discount pricing is not applicable for auction offer."
- },
- "25762": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "availableQuantity is not applicable for auction offer."
- },
- "25763": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "quantityLimitPerBuyer is not applicable for auction offer."
- },
- "25764": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "eBayPlusIfEligible is not applicable for auction offer."
- },
- "25766": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The takeBackPolicyId field must be a long value type. Please correct the error."
- },
- "25767": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The productCompliancePolicyId field must be a long value type. Please correct the error."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- },
- "25025": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "delete": {
- "tags": [
- "offer"
- ],
- "description": "If used against an unpublished offer, this call will permanently delete that offer. In the case of a published offer (or live eBay listing), a successful call will either end the single-variation listing associated with the offer, or it will remove that product variation from the eBay listing and also automatically remove that product variation from the inventory item group. In the case of a multiple-variation listing, the deleteOffer will not remove the product variation from the listing if that variation has one or more sales. If that product variation has one or more sales, the seller can alternately just set the available quantity of that product variation to 0, so it is not available in the eBay search or View Item page, and then the seller can remove that product variation from the inventory item group at a later time.",
- "operationId": "deleteOffer",
- "parameters": [
- {
- "name": "offerId",
- "in": "path",
- "description": "This path parameter specifies the unique identifier of the offer being deleted.
Use the getOffers method to retrieve offer IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25713": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This Offer is not available : {additionalInfo}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/offer/get_listing_fees": {
- "post": {
- "tags": [
- "offer"
- ],
- "description": "This call is used to retrieve the expected listing fees for up to 250 unpublished offers. An array of one or more offerId values are passed in under the offers container.
In the response payload, all listing fees are grouped by eBay marketplace, and listing fees per offer are not shown. A fees container will be returned for each eBay marketplace where the seller is selling the products associated with the specified offers.
Errors will occur if the seller passes in offerIds that represent published offers, so this call should be made before the seller publishes offers with the publishOffer.",
- "operationId": "getListingFees",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "List of offers that needs fee information",
- "content": {
- "application/json": {
- "schema": {
- "description": "List of offers that needs fee information",
- "$ref": "#/components/schemas/OfferKeysWithId"
- }
- }
- },
- "required": false
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/FeesSummaryResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25709": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid value for {fieldName}. {additionalInfo}"
- },
- "25754": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "One or more provided offerId(s) are invalid. All offerId(s) in the request should belong to an inventoryItem or inventoryItemGroup for a specific marketplaceId and format."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/offer/{offerId}/publish": {
- "post": {
- "tags": [
- "offer"
- ],
- "description": "Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call is used to convert an unpublished offer into a published offer, or live eBay listing. The unique identifier of the offer (offerId) is passed in at the end of the call URI.
Important!Publish offer note: Fields may be optional or conditionally required when calling the create or update methods, but become required when publishing the offer to create active listings. For this method, see Offer fields for a list of fields required to publish an offer.
For those who prefer to publish multiple offers (up to 25 at a time) with one call, the bulkPublishOffer method can be used. In the case of a multiple-variation listing, the publishOfferByInventoryItemGroup call should be used instead, as this call will convert all unpublished offers associated with an inventory item group into a multiple-variation listing.",
- "operationId": "publishOffer",
- "parameters": [
- {
- "name": "offerId",
- "in": "path",
- "description": "This path parameter specifies the unique identifier of the offer that is to be published.
Use the getOffers method to retrieve offer IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/PublishResponse"
- }
- }
+ "AvailabilityDistribution": {
+ "type": "object",
+ "properties": {
+ "fulfillmentTime": {
+ "description": "This container is used to indicate the expected fulfillment time if the inventory item is shipped from the warehouse location identified in the corresponding merchantLocationKey field. The fulfillment time is the estimated number of business days after purchase that the buyer can expect the item to be delivered.
This field is optional, and is used by eBay to provide the estimated delivery date to buyers. This field is returned by getInventoryItem and getInventoryItems if set for the inventory item.",
+ "$ref": "#/components/schemas/TimeDuration"
+ },
+ "merchantLocationKey": {
+ "type": "string",
+ "description": "The unique identifier of an inventory location where quantity is available for the inventory item. This field is conditionally required to identify the inventory location that has quantity of the inventory item.
Use the getInventoryLocations method to retrieve merchant location keys."
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "The integer value passed into this field indicates the quantity of the inventory item that is available at this inventory location. This field is conditionally required.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used to set the available quantity of the inventory item at one or more warehouse locations."
},
- "x-response-codes": {
- "errors": {
- "25028": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not applicable and has been dropped"
- },
- "25030": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not applicable for the condition and has been dropped"
- },
- "25033": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Duplicate policy IDs found"
- },
- "25037": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Item level Eco Participation Fee will be ignored"
- },
- "25401": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid listing format removed {additionalInfo}"
- },
- "25402": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "System warning. {additionalInfo}"
- },
- "25753": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "A user error has occurred. {additionalInfo}"
- },
- "25003": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}"
- },
- "25004": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}"
- },
- "25005": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}"
- },
- "25006": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}"
- },
- "25007": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}"
- },
- "25008": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}"
- },
- "25009": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}"
- },
- "25011": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid tax information. {additionalInfo}"
- },
- "25012": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid inventory location. {additionalInfo}"
- },
- "25013": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
- },
- "25014": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}"
- },
- "25015": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}"
- },
- "25016": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The {fieldName} value is invalid. {additionalInfo}"
- },
- "25017": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
- },
- "25018": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
- },
- "25019": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
- },
- "25020": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}"
- },
- "25021": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}"
- },
- "25022": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25023": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid compatibility information. {additionalInfo}"
- },
- "25026": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Selling limit exceeded. {additionalInfo}"
- },
- "25029": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is required for this category."
- },
- "25031": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not valid and needs to be a number between {min} and {max}"
- },
- "25032": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not valid"
- },
- "25034": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Only {max value} policies can be specified"
- },
- "25035": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The specified policy is not found for the market place"
- },
- "25036": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The policy(ies) {PolicyId} is not of type {PolicyEnum}"
- },
- "25038": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer or is ending within 12 hours"
- },
- "25039": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
- },
- "25040": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
- },
- "25041": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s)."
- },
- "25042": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, free shipping must be provided."
- },
- "25043": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, returns must be accepted."
- },
- "25044": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, refund must be provided as Money Back."
- },
- "25045": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days."
- },
- "25046": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, seller must pay the cost for return shipping."
- },
- "25047": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition"
- },
- "25048": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition in this Category"
- },
- "25049": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition for the selected Brand"
- },
- "25050": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title."
- },
- "25051": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle"
- },
- "25052": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, at least {replaceable_value} images must be provided"
- },
- "25076": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{replaceable_value} ID(s) {replaceable_value} not found. Please use valid ID(s)."
- },
- "25077": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Duplicate Regulatory ID(s) {replaceable_value} sent in the request. Duplicate ID(s) have been ignored."
- },
- "25078": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Hazmat structure incorrect for {replaceable_value}."
- },
- "25079": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Repair score invalid. Repair score must be in the range from {replaceable_value} to {replaceable_value} with one decimal place."
- },
- "25080": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The value of the {0} field is invalid. Field must not exceed {replaceable_value} characters."
- },
- "25081": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Hazardous material information incomplete. Your listing must include hazardous statements."
- },
- "25083": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Energy efficiency image is missing. Image is required with image description."
- },
- "25084": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The listing must have both an energy efficiency label and a product information sheet."
- },
- "25086": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The URL provided must be an eBay Picture Service URL."
- },
- "25088": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The email address provided is formatted incorrectly."
- },
- "25089": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} global compliance policies allowed. Excess policies ignored."
- },
- "25090": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} compliance policies per region allowed. Excess policies ignored."
- },
- "25091": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than a total of {replaceable_value} compliance policies allowed. Excess policies ignored."
- },
- "25092": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} global takeback policy allowed."
- },
- "25093": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} takeback policy per region allowed. Excess policies ignored."
- },
- "25094": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than a total of {replaceable_value} takeback policies allowed."
- },
- "25095": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Region invalid for regional custom policy. Regions allowed are {replaceable_value}."
- },
- "25104": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Regulatory document ID(s) {replaceable_value} not found. Please use valid ID(s)."
- },
- "25106": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Regulatory document structure incorrect. Max allowed number of entries is {replaceable_value}."
- },
- "25107": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid document state for ID(s) {replaceable_value}. Documents must be in the SUBMITTED or ACCEPTED state."
- },
- "25108": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Product Safety structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
- },
- "25109": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Product Safety information incomplete. Your listing must include product safety pictograms & statements."
- },
- "25110": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Manufacturer address information is incomplete. When providing the address, please provide the street, city, postal code and country"
- },
- "25111": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Manufacturer information is incomplete. Please provide the company name."
- },
- "25112": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
- },
- "25113": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person address information is incomplete. When providing the address, please provide the street, city, postal code and country"
- },
- "25114": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person information is incomplete. Please provide the company name."
- },
- "25115": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Either the Manufacturer or at least one of the Responsible Persons must be located in the EU."
- },
- "25116": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Please provide a minimum of {replaceable_value} and a maximum of {replaceable_value} types for a Responsible Person."
- },
- "25118": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller must provide at least one form of contact info for Manufacturer - either phone, email or address."
- },
- "25119": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller must provide at least one form of contact info for Responsible Person - either phone, email or address."
- },
- "25601": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{fieldName} is an invalid attribute."
- },
- "25604": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25713": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This Offer is not available : {additionalInfo}."
- },
- "25752": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate provided is invalid."
- },
- "25760": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "shipToLocationAvailability quantity insufficient to create auction listings."
- },
- "25766": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The takeBackPolicyId field must be a long value type. Please correct the error."
- },
- "25767": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The productCompliancePolicyId field must be a long value type. Please correct the error."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "A system error has occurred. {additionalInfo}"
- },
- "25025": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/offer/publish_by_inventory_item_group": {
- "post": {
- "tags": [
- "offer"
- ],
- "description": "Note: Please note that any eBay listing created using the Inventory API cannot be revised or relisted using the Trading API calls.
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
This call is used to convert all unpublished offers associated with an inventory item group into an active, multiple-variation listing.
Important!Publish offer note: Fields may be optional or conditionally required when calling the create or update methods, but become required when publishing the offer to create active listings. For this method, see Offer fields for a list of fields required to publish an offer.
The unique identifier of the inventory item group (inventoryItemGroupKey) is passed in the request payload. All inventory items and their corresponding offers in the inventory item group must be valid (meet all requirements) for the publishOfferByInventoryItemGroup call to be completely successful. For any inventory items in the group that are missing required data or have no corresponding offers, the publishOfferByInventoryItemGroup will create a new multiple-variation listing, but any inventory items with missing required data/offers will not be in the newly-created listing. If any inventory items in the group to be published have invalid data, or one or more of the inventory items have conflicting data with one another, the publishOfferByInventoryItemGroup call will fail. Be sure to check for any error or warning messages in the call response for any applicable information about one or more inventory items/offers having issues.",
- "operationId": "publishOfferByInventoryItemGroup",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "The identifier of the inventory item group to publish and the eBay marketplace where the listing will be published is needed in the request payload.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The identifier of the inventory item group to publish and the eBay marketplace where the listing will be published is needed in the request payload.",
- "$ref": "#/components/schemas/PublishByInventoryItemGroupRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/PublishResponse"
- }
- }
+ "AvailabilityWithAll": {
+ "type": "object",
+ "properties": {
+ "pickupAtLocationAvailability": {
+ "type": "array",
+ "description": "This container consists of an array of one or more of the merchant's physical stores where the inventory item is available for in-store pickup.
The store ID, the quantity available, and the fulfillment time (how soon the item will be ready for pickup after the order occurs) are all returned in this container.",
+ "items": {
+ "$ref": "#/components/schemas/PickupAtLocationAvailability"
+ }
+ },
+ "shipToLocationAvailability": {
+ "description": "This container specifies the quantity of the inventory items that are available for a standard purchase, where the item is shipped to the buyer.",
+ "$ref": "#/components/schemas/ShipToLocationAvailabilityWithAll"
+ }
+ },
+ "description": "This type is used to specify the quantity of the inventory items that are available for purchase if the items will be shipped to the buyer, and the quantity of the inventory items that are available for In-Store Pickup at one or more of the merchant's physical stores.
In-Store Pickup is only available to large merchants selling on the US, UK, Germany, and Australia sites."
},
- "x-response-codes": {
- "errors": {
- "25028": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not applicable and has been dropped"
- },
- "25030": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not applicable for the condition and has been dropped"
- },
- "25033": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Duplicate policy IDs found"
- },
- "25037": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Item level Eco Participation Fee will be ignored"
- },
- "25401": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Invalid listing options removed. {additionalInfo}"
- },
- "25402": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System warning. {additionalInfo}"
- },
- "25753": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate is in the past or the offer is live. Value is not updated on the listing."
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Any User error. {additionalInfo}"
- },
- "25003": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid price. {additionalInfo}"
- },
- "25004": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid quantity. {additionalInfo}"
- },
- "25005": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid category. {additionalInfo}"
- },
- "25006": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid listing option. {additionalInfo}"
- },
- "25007": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid Shipping policy information. {additionalInfo}"
- },
- "25008": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid Payment policy information. {additionalInfo}"
- },
- "25009": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid Return policy information. {additionalInfo}"
- },
- "25011": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid tax information. {additionalInfo}"
- },
- "25012": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid location. {additionalInfo}"
- },
- "25013": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25013 Invalid data in the Inventory Item Group for the full list of messages returned and any available troubleshooting information."
- },
- "25014": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid pictures. {additionalInfo}"
- },
- "25015": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid picture URL. {additionalInfo}"
- },
- "25016": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid {fieldName}. {additionalInfo}"
- },
- "25017": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25017 Missing information in fields for the full list of messages returned and any available troubleshooting information."
- },
- "25018": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25018 Incomplete account information for the full list of messages returned and any available troubleshooting information."
- },
- "25019": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This error code is associated with multiple possible errors. See 25019 Cannot revise the listing for the full list of messages returned and any available troubleshooting information."
- },
- "25020": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid package details. {additionalInfo}"
- },
- "25021": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid condition information. {additionalInfo}"
- },
- "25022": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25023": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid compatibility information. {additionalInfo}"
- },
- "25026": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Selling limits exceeded. {additionalInfo}"
- },
- "25029": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is required for this category."
- },
- "25031": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not valid and needs to be a number between {min} and {max}"
- },
- "25032": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{field} is not valid"
- },
- "25034": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Only {max value} policies can be specified"
- },
- "25035": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The specified policy is not found for the market place"
- },
- "25036": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The policy(ies) {PolicyId} is not of type {PolicyEnum}"
- },
- "25038": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer or is ending within 12 hours"
- },
- "25039": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
- },
- "25040": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours"
- },
- "25041": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s)."
- },
- "25042": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, free shipping must be provided."
- },
- "25043": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, returns must be accepted."
- },
- "25044": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, refund must be provided as Money Back."
- },
- "25045": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days."
- },
- "25046": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, seller must pay the cost for return shipping."
- },
- "25047": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition"
- },
- "25048": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition in this Category"
- },
- "25049": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller is not eligible to use Refurbished Item Condition for the selected Brand"
- },
- "25050": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title."
- },
- "25051": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle"
- },
- "25052": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "When listing an item with Refurbished condition, at least {replaceable_value} images must be provided"
- },
- "25076": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{replaceable_value} ID(s) {replaceable_value} not found. Please use valid ID(s)."
- },
- "25077": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Duplicate Regulatory ID(s) {replaceable_value} sent in the request. Duplicate ID(s) have been ignored."
- },
- "25078": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Hazmat structure incorrect for {replaceable_value}."
- },
- "25079": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Repair score invalid. Repair score must be in the range from {replaceable_value} to {replaceable_value} with one decimal place."
- },
- "25080": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The value of the {0} field is invalid. Field must not exceed {replaceable_value} characters."
- },
- "25081": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Hazardous material information incomplete. Your listing must include hazardous statements."
- },
- "25083": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Energy efficiency image is missing. Image is required with image description."
- },
- "25084": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The listing must have both an energy efficiency label and a product information sheet."
- },
- "25086": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The URL provided must be an eBay Picture Service URL."
- },
- "25088": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The email address provided is formatted incorrectly."
- },
- "25089": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} global compliance policies allowed. Excess policies ignored."
- },
- "25090": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} compliance policies per region allowed. Excess policies ignored."
- },
- "25091": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than a total of {replaceable_value} compliance policies allowed. Excess policies ignored."
- },
- "25092": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} global takeback policy allowed."
- },
- "25093": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than {replaceable_value} takeback policy per region allowed. Excess policies ignored."
- },
- "25094": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No more than a total of {replaceable_value} takeback policies allowed."
- },
- "25095": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Region invalid for regional custom policy. Regions allowed are {replaceable_value}."
- },
- "25104": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Regulatory document ID(s) {replaceable_value} not found. Please use valid ID(s)."
- },
- "25106": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Regulatory document structure incorrect. Max allowed number of entries is {replaceable_value}."
- },
- "25107": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid document state for ID(s) {replaceable_value}. Documents must be in the SUBMITTED or ACCEPTED state."
- },
- "25108": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Product Safety structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
- },
- "25109": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Product Safety information incomplete. Your listing must include product safety pictograms & statements."
- },
- "25110": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Manufacturer address information is incomplete. When providing the address, please provide the street, city, postal code and country"
- },
- "25111": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Manufacturer information is incomplete. Please provide the company name."
- },
- "25112": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}."
- },
- "25113": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person address information is incomplete. When providing the address, please provide the street, city, postal code and country"
- },
- "25114": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Responsible Person information is incomplete. Please provide the company name."
- },
- "25115": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Either the Manufacturer or at least one of the Responsible Persons must be located in the EU."
- },
- "25116": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Please provide a minimum of {replaceable_value} and a maximum of {replaceable_value} types for a Responsible Person."
- },
- "25118": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller must provide at least one form of contact info for Manufacturer - either phone, email or address."
- },
- "25119": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Seller must provide at least one form of contact info for Responsible Person - either phone, email or address."
- },
- "25601": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid attribute. {fieldName}"
- },
- "25604": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25705": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system."
- },
- "25752": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "listingStartDate provided is invalid."
- },
- "25766": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The takeBackPolicyId field must be a long value type. Please correct the error."
- },
- "25767": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "The productCompliancePolicyId field must be a long value type. Please correct the error."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Any System error. {additionalInfo}"
- },
- "25025": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Concurrent access of Inventory or InventoryItemGroup. Please try again later"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/offer/{offerId}/withdraw": {
- "post": {
- "tags": [
- "offer"
- ],
- "description": "This call is used to end a single-variation listing that is associated with the specified offer. This call is used in place of the deleteOffer call if the seller only wants to end the listing associated with the offer but does not want to delete the offer object. With this call, the offer object remains, but it goes into the unpublished state, and will require a publishOffer call to relist the offer.
To end a multiple-variation listing that is associated with an inventory item group, the withdrawOfferByInventoryItemGroup method can be used. This call only ends the multiple-variation listing associated with an inventory item group but does not delete the inventory item group object, nor does it delete any of the offers associated with the inventory item group, but instead all of these offers go into the unpublished state.",
- "operationId": "withdrawOffer",
- "parameters": [
- {
- "name": "offerId",
- "in": "path",
- "description": "This path parameter specifies the unique identifier of the offer that is to be withdrawn.
Use the getOffers method to retrieve offer IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/WithdrawResponse"
- }
- }
+ "BaseResponse": {
+ "type": "object",
+ "properties": {
+ "warnings": {
+ "type": "array",
+ "description": "This container will be returned in a call response payload if one or more warnings or errors are triggered when an Inventory API call is made. This container will contain detailed information about the error or warning.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This is the base response of the createOrReplaceInventoryItem, createOrReplaceInventoryItemGroup, and createOrReplaceProductCompatibility calls. A response payload will only be returned for these three calls if one or more errors or warnings occur with the call."
},
- "x-response-codes": {
- "errors": {
- "25402": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System warning. {additionalInfo}"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25002": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Any User error. {additionalInfo}"
- },
- "25713": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "This Offer is not available : {additionalInfo}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Any System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/offer/withdraw_by_inventory_item_group": {
- "post": {
- "tags": [
- "offer"
- ],
- "description": "This call is used to end a multiple-variation eBay listing that is associated with the specified inventory item group. This call only ends multiple-variation eBay listing associated with the inventory item group but does not delete the inventory item group object. Similarly, this call also does not delete any of the offers associated with the inventory item group, but instead all of these offers go into the unpublished state. If the seller wanted to relist the multiple-variation eBay listing, they could use the publishOfferByInventoryItemGroup method.",
- "operationId": "withdrawOfferByInventoryItemGroup",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "The base request of the withdrawOfferByInventoryItemGroup call.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The base request of the withdrawOfferByInventoryItemGroup call.",
- "$ref": "#/components/schemas/WithdrawByInventoryItemGroupRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25725": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "No offer found"
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "Any System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/location/{merchantLocationKey}": {
- "get": {
- "tags": [
- "location"
- ],
- "description": "This call retrieves all defined details of the inventory location that is specified by the merchantLocationKey path parameter.A successful call will return an HTTP status value of 200 OK.
",
- "operationId": "getInventoryLocation",
- "parameters": [
- {
- "name": "merchantLocationKey",
- "in": "path",
- "description": "This path parameter specifies the unique merchant-defined key (ID) for an inventory location that is being retrieved.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/InventoryLocationResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25804": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25805": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{fieldName} Not Found."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "post": {
- "tags": [
- "location"
- ],
- "description": "Use this call to create a new inventory location. In order to create and publish an offer (and create an eBay listing), a seller must have at least one location, as every offer must be associated with at least one location.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Location fields for a list of fields required to publish an offer.
Upon first creating an inventory location, only a seller-defined location identifier and a physical location is required, and once set, these values can not be changed. The unique identifier value (merchantLocationKey) is passed in at the end of the call URI. This merchantLocationKey value will be used in other Inventory Location calls to identify the location to perform an action against.
When creating an inventory location, the locationTypes can be specified to define the function of a location. At this time, the following locationTypes are supported:
- Fulfillment center locations are used by sellers selling products through the Multi-warehouse program to get improved estimated delivery dates on their listings. A full address is required when creating a fulfillment center location, as well as the fulfillmentCenterSpecifications of the location. For more information on using the fulfillment center location type to get improved delivery dates, see Multi-warehouse program.
- Warehouse locations are used for traditional shipping. A full street address is not needed, but the postalCode and country OR city, stateOrProvince, and country of the location must be provided.
- Store locations are generally used by merchants selling product through the In-Store Pickup program. A full address is required when creating a store location.
Note that all inventory locations are \"enabled\" by default when they are created, and you must specifically disable them (by passing in a value of DISABLED in the merchantLocationStatus field) if you want them to be set to the disabled state. The seller's inventory cannot be loaded to inventory locations in the disabled state.
Unless one or more errors and/or warnings occur with the call, there is no response payload for this call. A successful call will return an HTTP status value of 204 No Content.
",
- "operationId": "createInventoryLocation",
- "parameters": [
- {
- "name": "merchantLocationKey",
- "in": "path",
- "description": "This path parameter specifies the unique, seller-defined key (ID) for an inventory location.
Max length: 36",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "Inventory Location details",
- "content": {
- "application/json": {
- "schema": {
- "description": "Inventory Location details",
- "$ref": "#/components/schemas/InventoryLocationFull"
- }
- }
- },
- "required": true
- },
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25800": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid {fieldName}."
- },
- "25801": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Missing field {fieldName}."
- },
- "25802": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25803": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{fieldName} already exists."
- },
- "25804": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- }
- }
- }
- },
- "409": {
- "description": "Location Already Exists"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- },
- "delete": {
- "tags": [
- "location"
- ],
- "description": "This call deletes the inventory location that is specified in the merchantLocationKey path parameter. Note that deleting a location will not affect any active eBay listings associated with the deleted location, but the seller will not be able modify the offers associated with the location once it is deleted.
Note: Deletion is not currently supported for fulfillment center locations, as location mappings will still be retained despite the location being deleted. Instead, fulfillment center locations should be disabled using the disableInventoryLocation method.Unless one or more errors and/or warnings occur with the call, there is no response payload for this call. A successful call will return an HTTP status value of 200 OK.
",
- "operationId": "deleteInventoryLocation",
- "parameters": [
- {
- "name": "merchantLocationKey",
- "in": "path",
- "description": "This path parameter specifies the unique merchant-defined key (ID) for the inventory location that is to be deleted.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "Success"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25802": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25804": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25805": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{fieldName} Not Found."
- },
- "25806": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Deletion is not allowed when the location type of an inventory location has been set to fulfillment center. However, you may disable it."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/location/{merchantLocationKey}/disable": {
- "post": {
- "tags": [
- "location"
- ],
- "description": "This call disables the inventory location that is specified in the merchantLocationKey path parameter. Sellers can not load/modify inventory to disabled locations. Note that disabling a location will not affect any active eBay listings associated with the disabled location, but the seller will not be able modify the offers associated with a disabled location.
A successful call will return an HTTP status value of 200 OK.
",
- "operationId": "disableInventoryLocation",
- "parameters": [
- {
- "name": "merchantLocationKey",
- "in": "path",
- "description": "This path parameter specifies the unique merchant-defined key (ID) for an inventory location that is to be disabled.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25802": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25804": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25805": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{fieldName} Not Found."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/location/{merchantLocationKey}/enable": {
- "post": {
- "tags": [
- "location"
- ],
- "description": "This call enables a disabled inventory location that is specified in the merchantLocationKey path parameter. Once a disabled location is enabled, sellers can start loading/modifying inventory to that location.
A successful call will return an HTTP status value of 200 OK.
",
- "operationId": "enableInventoryLocation",
- "parameters": [
- {
- "name": "merchantLocationKey",
- "in": "path",
- "description": "This path parameter specifies unique merchant-defined key (ID) for a disabled inventory location that is to be enabled.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25802": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25804": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25805": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{fieldName} Not Found."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/location": {
- "get": {
- "tags": [
- "location"
- ],
- "description": "This call retrieves all defined details for every inventory location associated with the seller's account. There are no required parameters for this call and no request payload. However, there are two optional query parameters, limit and offset. The limit query parameter sets the maximum number of locations returned on one page of data, and the offset query parameter specifies the page of data to return. These query parameters are discussed more in the URI parameters table below. The authorization HTTP header is the only required request header for this call.
A successful call will return an HTTP status value of 200 OK.
",
- "operationId": "getInventoryLocations",
- "parameters": [
- {
- "name": "limit",
- "in": "query",
- "description": "The value passed in this query parameter sets the maximum number of records to return per page of data. Although this field is a string, the value passed in this field should be a positive integer value. If this query parameter is not set, up to 100 records will be returned on each page of results.
Min: 1",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "Specifies the number of locations to skip in the result set before returning the first location in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/LocationResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System error. {additionalInfo}"
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/location/{merchantLocationKey}/update_location_details": {
- "post": {
- "tags": [
- "location"
- ],
- "description": "Use this call to update location details for an existing inventory location. Specify the inventory location you want to update using the merchantLocationKey path parameter.
You can update the following text-based fields: name, phone, timeZoneId, geoCoordinates, fulfillmentCenterSpecifications, locationTypes, locationWebUrl, locationInstructions and locationAdditionalInformation any number of times for any location type.
For warehouse and store inventory locations, address fields can be updated any number of times. Address fields cannot be updated for fulfillment center locations. However, if any address fields were omitted during the createInventoryLocation call, they can be added through this method.
Note: When updating a warehouse location to a fulfillment center, sellers can update any of the address fields a single time during the same call used to make this update. After this, they can no longer be updated.For store locations, the operating hours and/or the special hours can also be updated.
Whatever text is passed in for these fields in an updateInventoryLocation call will replace the current text strings defined for these fields.
Unless one or more errors and/or warnings occurs with the call, there is no response payload for this call. A successful call will return an HTTP status value of 204 No Content.
",
- "operationId": "updateInventoryLocation",
- "parameters": [
- {
- "name": "merchantLocationKey",
- "in": "path",
- "description": "This path parameter specifies the unique merchant-defined key (ID) for an inventory location that is to be updated.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "The inventory location details to be updated.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The inventory location details to be updated.",
- "$ref": "#/components/schemas/InventoryLocation"
- }
- }
- },
- "required": true
- },
- "responses": {
- "204": {
- "description": "Success"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "25800": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Invalid {fieldName}."
- },
- "25801": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Missing field {fieldName}."
- },
- "25802": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25803": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{fieldName} already exists."
- },
- "25804": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "Input error. {additionalInfo}"
- },
- "25805": {
- "domain": "API_INVENTORY",
- "category": "REQUEST",
- "description": "{fieldName} Not Found."
+ "BestOffer": {
+ "type": "object",
+ "properties": {
+ "autoAcceptPrice": {
+ "description": "This is the price at which Best Offers are automatically accepted. If a buyer submits a Best Offer that is equal to or above this value, the offer is automatically accepted on behalf of the seller. This field is only applicable if the bestOfferEnabled value is set to true.
The price set here must be lower than the current 'Buy it Now' price. This field is only returned by getOffer and getOffers if set.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "autoDeclinePrice": {
+ "description": "This is the price at which Best Offers are automatically declined. If a buyer submits a Best Offer that is equal to or below this value, the offer is automatically declined on behalf of the seller. This field is only applicable if the bestOfferEnabled value is set to true.
The price set here must be lower than the current 'Buy it Now' price and the price set in the autoAcceptPrice field (if used). This field is only returned by getOffer and getOffers if set.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "bestOfferEnabled": {
+ "type": "boolean",
+ "description": "This field indicates whether or not the Best Offer feature is enabled for the listing. A seller can enable the Best Offer feature for a listing as long as the category supports the Best Offer feature.
The seller includes this field and sets its value to true to enable Best Offer feature.
Note: Best Offer is not available for multi-variation listings."
+ }
+ },
+ "description": "This type is used by the bestOfferTerms container, which is used if the seller would like to support the Best Offer feature on their listing."
+ },
+ "BulkEbayOfferDetailsWithKeys": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "The details of each offer that is being created is passed in under this container. Up to 25 offers can be created with one bulkCreateOffer call.",
+ "items": {
+ "$ref": "#/components/schemas/EbayOfferDetailsWithKeys"
+ }
+ }
+ },
+ "description": "This type is used by the base request of the bulkCreateOffer method, which is used to create up to 25 new offers."
+ },
+ "BulkGetInventoryItem": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "The seller passes in multiple SKU values under this container to retrieve multiple inventory item records. Up to 25 inventory item records can be retrieved at one time.",
+ "items": {
+ "$ref": "#/components/schemas/GetInventoryItem"
+ }
+ }
+ },
+ "description": "This type is used by the base request of the bulkGetInventoryItem method."
+ },
+ "BulkGetInventoryItemResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "This is the base container of the bulkGetInventoryItem response. The results of each attempted inventory item retrieval is captured under this container.",
+ "items": {
+ "$ref": "#/components/schemas/GetInventoryItemResponse"
+ }
+ }
+ },
+ "description": "This type is used by the base response of the bulkGetInventoryItem method."
+ },
+ "BulkInventoryItem": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "The details of each inventory item that is being created or updated is passed in under this container. Up to 25 inventory item records can be created and/or updated with one bulkCreateOrReplaceInventoryItem call.",
+ "items": {
+ "$ref": "#/components/schemas/InventoryItemWithSkuLocale"
+ }
+ }
+ },
+ "description": "The base request of the bulkCreateOrReplaceInventoryItem method."
+ },
+ "BulkInventoryItemResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "This is the base container of the bulkCreateOrReplaceInventoryItem response. The results of each attempted inventory item creation/update is captured under this container.",
+ "items": {
+ "$ref": "#/components/schemas/InventoryItemResponse"
+ }
+ }
+ },
+ "description": "This type is used by the base response of the bulkCreateOrReplaceInventoryItem method."
+ },
+ "BulkMigrateListing": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "This is the base container of the bulkMigrateListings request payload. One to five eBay listings will be included under this container.",
+ "items": {
+ "$ref": "#/components/schemas/MigrateListing"
+ }
+ }
+ },
+ "description": "This type is used by the base container of the bulkMigrateListings request payload."
+ },
+ "BulkMigrateListingResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "This is the base container of the response payload of the bulkMigrateListings call. The results of each attempted listing migration is captured under this container.",
+ "items": {
+ "$ref": "#/components/schemas/MigrateListingResponse"
+ }
+ }
+ },
+ "description": "This type is used by the response payload of the bulkMigrateListings call."
+ },
+ "BulkOffer": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "This container is used to pass in an array of offers to publish. Up to 25 offers can be published with one bulkPublishOffer method.",
+ "items": {
+ "$ref": "#/components/schemas/OfferKeyWithId"
+ }
+ }
+ },
+ "description": "This type is used by the base request of the bulkPublishOffer method, which is used to publish up to 25 different offers."
+ },
+ "BulkOfferResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/OfferSkuResponse"
+ }
+ }
+ },
+ "description": "This type is used by the base response of the bulkCreateOffer method."
+ },
+ "BulkPriceQuantity": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "This container is used by the seller to update the total 'ship-to-home' quantity of one or more inventory items (up to 25) and/or to update the price and/or quantity of one or more specific published offers.",
+ "items": {
+ "$ref": "#/components/schemas/PriceQuantity"
+ }
+ }
+ },
+ "description": "This type is used by the base request payload of the bulkUpdatePriceQuantity call. The bulkUpdatePriceQuantity call allows the seller to update the total 'ship-to-home' quantity of one or more inventory items (up to 25) and/or to update the price and/or quantity of one or more specific published offers."
+ },
+ "BulkPriceQuantityResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "This container will return an HTTP status code, offer ID, and SKU value for each offer/inventory item being updated, as well as an errors and/or warnings container if any errors or warnings are triggered while trying to update those offers/inventory items.",
+ "items": {
+ "$ref": "#/components/schemas/PriceQuantityResponse"
+ }
+ }
+ },
+ "description": "This type is use by the base response payload of the bulkUpdatePriceQuantity call. The bulkUpdatePriceQuantity call response will return an HTTP status code, offer ID, and SKU value for each offer/inventory item being updated, as well as an errors and/or warnings container if any errors or warnings are triggered while trying to update those offers/inventory items."
+ },
+ "BulkPublishResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "A node is returned under the responses container to indicate the success or failure of each offer that the seller was attempting to publish.",
+ "items": {
+ "$ref": "#/components/schemas/OfferResponseWithListingId"
+ }
+ }
+ },
+ "description": "This type is used by the base response of the bulkPublishOffer method."
+ },
+ "Charity": {
+ "type": "object",
+ "properties": {
+ "charityId": {
+ "type": "string",
+ "description": "The eBay-assigned unique identifier of the charitable organization that will receive a percentage of the sales proceeds. The charitable organization must be reqistered with the PayPal Giving Fund in order to receive sales proceeds through eBay listings.
This field is conditionally required if a seller is planning on donating a percentage of the sale proceeds to a charitable organization.
The eBay-assigned unique identifier of a charitable organization can be found using the getCharityOrgs method of the Charity API. In the getCharityOrgs response, this unique identifier is shown in the charityOrgId field."
+ },
+ "donationPercentage": {
+ "type": "string",
+ "description": "This field is the percentage of the purchase price that the charitable organization (identified in the charityId field) will receive for each sale that the listing generates. This field is conditionally required if a seller is planning on donating a percentage of the sale proceeds to a charitable organization. This numeric value can range from 10 to 100, and in any 5 (percent) increments in between this range (e.g. 10, 15, 20...95,... 100). The seller would pass in 10 for 10 percent, 15 for 15 percent, 20 for 20 percent, and so on, all the way to 100 for 100 percent."
+ }
+ },
+ "description": "This type is used to identify the charitable organization associated with the listing, and the percentage of the sale proceeds that the charitable organization will receive for each sale generated by the listing.
In order to receive a percentage of the sales proceeds, the charitable organization must be registered with the PayPal Giving Fund, which is a partner of eBay for Charity."
+ },
+ "Compatibility": {
+ "type": "object",
+ "properties": {
+ "compatibleProducts": {
+ "type": "array",
+ "description": "This container consists of an array of motor vehicles (make, model, year, trim, engine) that are compatible with the motor vehicle part or accessory specified by the sku value.",
+ "items": {
+ "$ref": "#/components/schemas/CompatibleProduct"
+ }
+ },
+ "sku": {
+ "type": "string",
+ "description": "The seller-defined SKU value of the inventory item that will be associated with the compatible vehicles.
Note: This field is not applicable to the createOrReplaceProductCompatibility method, as the SKU value for the inventory item is passed in as part of the call URI and not in the request payload. It is always returned with the getProductCompatibility method."
+ }
+ },
+ "description": "This type is used by the createOrReplaceProductCompatibility call to associate compatible vehicles to an inventory item. This type is also the base response of the getProductCompatibility call."
+ },
+ "CompatibleProduct": {
+ "type": "object",
+ "properties": {
+ "compatibilityProperties": {
+ "type": "array",
+ "description": "This container consists of an array of motor vehicles that are compatible with the motor vehicle part or accessory specified by the SKU value in the call URI. Each motor vehicle is defined through a separate set of name/value pairs. In the name field, the vehicle aspect (such as 'make', 'model', 'year', 'trim', or 'engine') will be identified, and the value field will be used to identify the value of each aspect.
The getCompatibilityProperties method of the Taxonomy API can be used to retrieve applicable vehicle aspect names for a specified category, and the getCompatibilityPropertyValues method of the Taxonomy API can be used to retrieve possible values for these same vehicle aspect names.
Below is an example of identifying one motor vehicle using the compatibilityProperties container:
"compatibilityProperties" : [
{
"name" : "make",
"value" : "Subaru"
},
{
"name" : "model",
"value" : "GL"
},
{
"name" : "year",
"value" : "1983"
},
{
"name" : "trim",
"value" : "Base Wagon 4-Door"
},
{
"name" : "engine",
"value" : "1.8L Turbocharged"
}
]
Typically, the make, model, and year of the motor vehicle are always required, with the trim and engine being necessary sometimes, but it will be dependent on the part or accessory, and on the vehicle class.
Note: The productFamilyProperties container is deprecated and should no longer be used. The compatibilityProperties container should be used instead.",
+ "items": {
+ "$ref": "#/components/schemas/NameValueList"
+ }
+ },
+ "notes": {
+ "type": "string",
+ "description": "This field is used by the seller to input any notes pertaining to the compatible vehicle list being defined. The seller might use this field to specify the placement of the part on a vehicle or other applicable information.
This field will only be returned if specified by the seller.
Max Length: 500
"
+ },
+ "productFamilyProperties": {
+ "description": "Important! The productFamilyProperties container is deprecated and should no longer be used. The compatibilityProperties container should be used instead.
Note that this container will not be returned in the getProductCompatibility call.",
+ "$ref": "#/components/schemas/ProductIdentifier"
+ }
+ },
+ "description": "This type is used to specify/indicate the motor vehicles that are compatible with the corresponding inventory item. "
+ },
+ "ConditionDescriptor": {
+ "type": "object",
+ "properties": {
+ "additionalInfo": {
+ "type": "string",
+ "description": "This string provides additional information about a condition descriptor. Open text is passed in this field.
In the case of trading cards and coins, this field houses the optional Certification Number condition descriptor for graded items.
Max Length: 30 characters"
+ },
+ "name": {
+ "type": "string",
+ "description": "This string provides the name of a condition descriptor. A numeric ID is passed in this field. This numeric ID maps to the name of a condition descriptor. Condition descriptor name-value pairs provide more information about an item's condition in a structured way.
To retrieve all condition descriptor name numeric IDs for a category, refer to the conditionDescriptorId field returned in the getItemConditionPolicies method of Metadata API.
In the case of trading cards, this field is used to provide condition descriptors for a card. For graded cards, the condition descriptors for Grader and Grade are required, while the condition descriptor for Certification Number is optional. For ungraded cards, only the Card Condition condition descriptor is required.
In the case of coins, this field is used to provide condition descriptors for a coin. For graded coins, the condition descriptors for Grader, Number Grade, and Letter Grade are required, while the condition descriptor for Certification Number is optional. For ungraded coins, only the Coin Condition condition descriptor is required."
+ },
+ "values": {
+ "type": "array",
+ "description": "This array provides the value(s) associated with a condition descriptor. One or more numeric IDs is passed in this field. Commas are used as delimiters between successive name/value pairs. These numeric IDs map to the values associated with a condition descriptor name. Condition descriptor name-value pairs provide more information about an item's condition in a structured way.
To retrieve all condition descriptor value numeric IDs for a category, refer to the ConditionDescriptorValueId array returned in the getItemConditionPolicies method of Metadata API.
In the case of trading cards, this field houses the information on the Grader and Grade descriptors of graded cards and the Card Condition descriptor for ungraded cards.
In the case of coins, this field houses the information on the Grader and Number Grade, and Letter Grade descriptors of graded coins and the Coin Condition descriptor for ungraded coins.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This type is used by the seller to provide additional information about the condition of an item in a structured format."
+ },
+ "CountryPolicy": {
+ "type": "object",
+ "properties": {
+ "country": {
+ "type": "string",
+ "description": "The two-letter ISO 3166-1 country code identifying the country to which the policy or policies specified in the corresponding policyIds array will apply. For implementation help, refer to eBay API documentation"
+ },
+ "policyIds": {
+ "type": "array",
+ "description": "An array of custom policy identifiers that apply to the country specified by listingPolicies.regionalTakeBackPolicies.countryPolicies.country.
Product compliance and take-back policy information may be returned using the following methods:- getCustomPolicies
Set policy_types to:PRODUCT_COMPLIANCE for product compliance policiesTAKE_BACK for takeback policies
This returns the list of specified policies and corresponding customPolicyId values a seller has created. - getCustomPolicy with
custom_policy_id = customPolicyId
Returns the details of the policy specified by customPolicyId
For information about creating and managing custom policies, refer to the custom_policy resource in the Sell Account API.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This type specifies custom product compliance and/or take-back policies that apply to a specified country."
+ },
+ "Dimension": {
+ "type": "object",
+ "properties": {
+ "height": {
+ "type": "number",
+ "description": "The actual height (in the measurement unit specified in the unit field) of the shipping package. All fields of the dimensions container are required if package dimensions are specified.
If a shipping package measured 21.5 inches in length, 15.0 inches in width, and 12.0 inches in height, the dimensions container would look as follows:
\"dimensions\": {
\"length\": 21.5,
\"width\": 15.0,
\"height\": 12.0,
\"unit\": \"INCH\"
}
"
+ },
+ "length": {
+ "type": "number",
+ "description": "The actual length (in the measurement unit specified in the unit field) of the shipping package. All fields of the dimensions container are required if package dimensions are specified.
If a shipping package measured 21.5 inches in length, 15.0 inches in width, and 12.0 inches in height, the dimensions container would look as follows:
\"dimensions\": {
\"length\": 21.5,
\"width\": 15.0,
\"height\": 12.0,
\"unit\": \"INCH\"
}
"
+ },
+ "unit": {
+ "type": "string",
+ "description": "The unit of measurement used to specify the dimensions of a shipping package. All fields of the dimensions container are required if package dimensions are specified. If the English system of measurement is being used, the applicable values for dimension units are FEET and INCH. If the metric system of measurement is being used, the applicable values for weight units are METER and CENTIMETER. The metric system is used by most countries outside of the US. For implementation help, refer to eBay API documentation"
+ },
+ "width": {
+ "type": "number",
+ "description": "The actual width (in the measurement unit specified in the unit field) of the shipping package. All fields of the dimensions container are required if package dimensions are specified.
If a shipping package measured 21.5 inches in length, 15.0 inches in width, and 12.0 inches in height, the dimensions container would look as follows:
\"dimensions\": {
\"length\": 21.5,
\"width\": 15.0,
\"height\": 12.0,
\"unit\": \"INCH\"
}
"
+ }
+ },
+ "description": "This type is used to specify the dimensions (and the unit used to measure those dimensions) of a shipping package. The dimensions container is conditionally required if the seller will be offering calculated shipping rates to determine shipping cost. See the Calculated shipping help page for more information on calculated shipping."
+ },
+ "Document": {
+ "type": "object",
+ "properties": {
+ "documentId": {
+ "type": "string",
+ "description": "The unique identifier of a regulatory document associated with the listing.
This value can be found in the response of the createDocument method of the Media API."
+ }
+ },
+ "description": "This type provides an array of one or more regulatory documents associated with a listing for Regulatory Compliance."
+ },
+ "EbayOfferDetailsWithAll": {
+ "type": "object",
+ "properties": {
+ "availableQuantity": {
+ "type": "integer",
+ "description": "This integer value indicates the quantity of the inventory item (specified by the sku value) that will be available for purchase by buyers shopping on the eBay site specified in the marketplaceId field.",
+ "format": "int32"
+ },
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the primary eBay category that the inventory item is listed under. This field is always returned for published offers, but is only returned if set for unpublished offers."
+ },
+ "charity": {
+ "description": "This container is returned if a charitable organization will receive a percentage of sale proceeds for each sale generated by the listing. This container consists of the charityId field to identify the charitable organization, and the donationPercentage field that indicates the percentage of the sales proceeds that will be donated to the charitable organization.",
+ "$ref": "#/components/schemas/Charity"
+ },
+ "extendedProducerResponsibility": {
+ "description": "This container is used to provide the eco-participation fee for a product. Use the getExtendedProducerResponsibilityPoliciesĀ method of theĀ Sell Metadata API to retrieve categories that support eco-participation fee for a specified marketplace.",
+ "$ref": "#/components/schemas/ExtendedProducerResponsibility"
+ },
+ "format": {
+ "type": "string",
+ "description": "This enumerated value indicates the listing format of the offer. For implementation help, refer to eBay API documentation"
+ },
+ "hideBuyerDetails": {
+ "type": "boolean",
+ "description": "This field is returned as true if the private listing feature has been enabled for the offer. Sellers may want to use this feature when they believe that a listing's potential bidders/buyers would not want their obfuscated user IDs (and feedback scores) exposed to other users.
This field is always returned even if not explicitly set in the offer. It defaults to false, so will get returned as false if seller does not set this feature with a 'Create' or 'Update' offer method."
+ },
+ "includeCatalogProductDetails": {
+ "type": "boolean",
+ "description": "This field indicates whether or not eBay product catalog details are applied to a listing. A value of true indicates the listing corresponds to the eBay product associated with the provided product identifier. The product identifier is provided in createOrReplaceInventoryItem.Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to 'true' if omitted.
"
+ },
+ "listing": {
+ "description": "For published offers, this container is always returned in the getOffer and getOffers calls, and includes the eBay listing ID associated with the offer, the status of the listing, and the quantity sold through the listing. The listing container is not returned at all for unpublished offers.",
+ "$ref": "#/components/schemas/ListingDetails"
+ },
+ "listingDescription": {
+ "type": "string",
+ "description": "The description of the eBay listing that is part of the unpublished or published offer. This field is always returned for published offers, but is only returned if set for unpublished offers.
Max Length: 500000 (which includes HTML markup/tags)"
+ },
+ "listingDuration": {
+ "type": "string",
+ "description": "This field indicates the number of days that the listing will be active.
This field is returned for both auction and fixed-price listings; however, the value returned for fixed-price listings will always be GTC. The GTC (Good 'Til Cancelled) listings are automatically renewed each calendar month until the seller decides to end the listing.
Note: If the listing duration expires for an auction offer, the listing then becomes available as a fixed-price offer and will be GTC. For implementation help, refer to eBay API documentation"
+ },
+ "listingPolicies": {
+ "description": "This container indicates the listing policies that are applied to the offer. Listing policies include business policies, custom listing policies, and fields that override shipping costs, enable eBay Plus eligibility, or enable the Best Offer feature.
It is required that the seller be opted into Business Policies before being able to create live eBay listings through the Inventory API. Sellers can opt-in to Business Policies through My eBay or by using the Account API's optInToProgram call. Payment, return, and fulfillment listing policies may be created/managed in My eBay or by using the listing policy calls of the sell Account API. The sell Account API can also be used to create and manage custom policies. For more information, see the sell Account API.
For unpublished offers where business policies have yet to be specified, this container will be returned as empty.",
+ "$ref": "#/components/schemas/ListingPolicies"
+ },
+ "listingStartDate": {
+ "type": "string",
+ "description": "This timestamp is the date/time (in UTC format) that the seller set for the scheduled listing. With the scheduled listing feature, the seller can set a time in the future that the listing will become active, instead of the listing becoming active immediately after a publishOffer call.
For example: 2023-05-30T19:08:00Z.
Scheduled listings do not always start at the exact date/time specified by the seller, but the date/time of the timestamp returned in getOffer/getOffers will be the same as the timestamp passed into a 'Create' or 'Update' offer call.
This field is returned if set for an offer."
+ },
+ "lotSize": {
+ "type": "integer",
+ "description": "This field is only applicable and returned if the listing is a lot listing. A lot listing is a listing that has multiple quantity of the same product. An example would be a set of four identical car tires. The integer value in this field is the number of identical items being sold through the lot listing.",
+ "format": "int32"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "This enumeration value is the unique identifier of the eBay site on which the offer is available, or will be made available. For implementation help, refer to eBay API documentation"
+ },
+ "merchantLocationKey": {
+ "type": "string",
+ "description": "The unique identifier of the inventory location. This identifier is set up by the merchant when the inventory location is first created with the createInventoryLocation call. Once this value is set for an inventory location, it can not be modified. To get more information about this inventory location, the getInventoryLocation method can be used, passing in this value at the end of the call URI.
This field is always returned for published offers, but is only returned if set for unpublished offers.
Max length: 36"
+ },
+ "offerId": {
+ "type": "string",
+ "description": "The unique identifier of the offer. This identifier is used in many offer-related calls, and it is also used in the bulkUpdatePriceQuantity call."
+ },
+ "pricingSummary": {
+ "description": "This container shows the listing price for the product offer, and if applicable, the settings for the Minimum Advertised Price and Strikethrough Pricing features. The Minimum Advertised Price feature is only available on the US site. Strikethrough Pricing is available on the US, eBay Motors, UK, Germany, Canada (English and French), France, Italy, and Spain sites.
For unpublished offers where pricing information has yet to be specified, this container will be returned as empty.",
+ "$ref": "#/components/schemas/PricingSummary"
+ },
+ "quantityLimitPerBuyer": {
+ "type": "integer",
+ "description": "This field is only applicable and set if the seller wishes to set a restriction on the purchase quantity of an inventory item per seller. If this field is set by the seller for the offer, then each distinct buyer may purchase up to, but not exceed the quantity in this field. So, if this field's value is 5, each buyer may purchase a quantity of the inventory item between one and five, and the purchases can occur in one multiple-quantity purchase, or over multiple transactions. If a buyer attempts to purchase one or more of these products, and the cumulative quantity will take the buyer beyond the quantity limit, that buyer will be blocked from that purchase.
",
+ "format": "int32"
+ },
+ "regulatory": {
+ "description": "This container is used by the seller to provide regulatory information.",
+ "$ref": "#/components/schemas/Regulatory"
+ },
+ "secondaryCategoryId": {
+ "type": "string",
+ "description": "The unique identifier for a secondary category. This field is applicable if the seller decides to list the item under two categories. Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. A fee may be charged when adding a secondary category to a listing.
Note: You cannot list US eBay Motors vehicles in two categories. However, you can list Parts & Accessories in two categories."
+ },
+ "sku": {
+ "type": "string",
+ "description": "This is the seller-defined SKU value of the product in the offer.
Max Length: 50
"
+ },
+ "status": {
+ "type": "string",
+ "description": "The enumeration value in this field specifies the status of the offer - either PUBLISHED or UNPUBLISHED. For implementation help, refer to eBay API documentation"
+ },
+ "storeCategoryNames": {
+ "type": "array",
+ "description": "This container is returned if the seller chose to place the inventory item into one or two eBay store categories that the seller has set up for their eBay store. The string value(s) in this container will be the full path(s) to the eBay store categories, as shown below:
\"storeCategoryNames\": [
\"/Fashion/Men/Shirts\",
\"/Fashion/Men/Accessories\" ],
",
+ "items": {
+ "type": "string"
+ }
+ },
+ "tax": {
+ "description": "This container is only returned if a sales tax table, a Value-Added Tax (VAT) rate, and/or a tax exception category code was applied to the offer. Only Business Sellers can apply VAT to their listings. It is possible that the applyTax field will be included with a value of true, but a buyer's purchase will not involve sales tax. A sales tax rate must be set up in the seller's sales tax table for the buyer's state/tax jurisdiction in order for that buyer to be subject to sales tax.
See the Using a tax table help page for more information on setting up and using a sales tax table.",
+ "$ref": "#/components/schemas/Tax"
+ }
+ },
+ "description": "This type provides details of an offer, and is used by the response payloads of the getOffer and the getOffers calls."
+ },
+ "EbayOfferDetailsWithId": {
+ "type": "object",
+ "properties": {
+ "availableQuantity": {
+ "type": "integer",
+ "description": "This integer value sets the quantity of the inventory item that will be available through the offer. Quantity must be set to 1 or more in order for the inventory item to be purchasable. This value should not be more than the quantity that is specified for the inventory item record. For auction listings, this field should not be provided.
If this field exists for the current unpublished or published offer, it should be provided again in the updateOffer call, even if the value is not changing. If this particular field is omitted in an updateOffer call, the general available quantity set for the inventory item record may be used instead, and this may not be accurate if the inventory item is being sold across multiple marketplaces.",
+ "format": "int32"
+ },
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay category that the inventory item is/will be listed under. This field is not immediately required for an unpublished offer, but will be required before publishing the offer. Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. The seller passes in a query string like \"iPhone 6\", and category ID values for suggested categories are returned in the response.
If this field exists for the current unpublished offer, it should be provided again in the updateOffer call, even if the eBay category is not changing. For a published offer (aka active eBay listing), this field must be provided or an error may occur. The eBay category of an active eBay listing cannot be changed once the listing has one or more sales, or if the listing is scheduled to end in less than 12 hours.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
true if the seller wishes to update a published or unpublished offer with the private listing feature. Alternatively, the seller could also remove the private listing feature (if already set for a published or unpublished offer) by including this field and setting it to false.
Sellers may want to use this option when they believe that a listing's potential bidders/buyers would not want their obfuscated user IDs (and feedback scores) exposed to other users."
+ },
+ "includeCatalogProductDetails": {
+ "type": "boolean",
+ "description": "This field indicates whether or not eBay product catalog details are applied to a listing. A value of true indicates the listing corresponds to the eBay product associated with the provided product identifier. The product identifier is provided in createOrReplaceInventoryItem.Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to 'true' if omitted.
"
+ },
+ "listingDescription": {
+ "type": "string",
+ "description": "The text in this field is (published offers), or will become (unpublished offers) the description of the eBay listing. This field is not immediately required for an unpublished offer, but will be required before publishing the offer. Note that if the listingDescription field was omitted in the createOffer call for the offer, the offer entity should have picked up the text provided in the product.description field of the inventory item record, or if the inventory item is part of a group, the offer entity should have picked up the text provided in the description field of the inventory item group record.
HTML tags and markup can be used in listing descriptions, but each character counts toward the max length limit.
Note: To ensure that their short listing description is optimized when viewed on mobile devices, sellers should strongly consider using eBay's View Item description summary feature when listing their items. Keep in mind that the 'short' listing description is what prospective buyers first see when they view the listing on a mobile device. The 'full' listing description is also available to mobile users when they click on the short listing description, but the full description is not automatically optimized for viewing in mobile devices, and many users won't even drill down to the full description.
Using HTML div and span tag attributes, this feature allows sellers to customize and fully control the short listing description that is displayed to prospective buyers when viewing the listing on a mobile device. The short listing description on mobile devices is limited to 800 characters, and whenever the full listing description (provided in this field, in UI, or seller tool) exceeds this limit, eBay uses a special algorithm to derive the best possible short listing description within the 800-character limit. However, due to some short listing description content being removed, it is definitely not ideal for the seller, and could lead to a bad buyer experience and possibly to a Significantly not as described (SNAD) case, since the buyer may not get complete details on the item when viewing the short listing description. See the eBay help page for more details on using the HTML div and span tags.
If this field exists for the current unpublished offer, it should be provided again in the updateOffer call, even if the text is not changing. For a published offer (aka active eBay listing), this field must be provided or an error may occur.
Max length: 500000 (which includes HTML markup/tags)"
+ },
+ "listingDuration": {
+ "type": "string",
+ "description": "This field indicates the number of days that the listing will be active. For fixed-price listings, this value must be set to GTC, but auction listings support different listing durations.
The GTC (Good 'Til Cancelled) listings are automatically renewed each calendar month until the seller decides to end the listing.
Note: If the listing duration expires for an auction offer without a winning bidder, the listing then becomes available as a fixed-price offer and listing duration will be GTC.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
For implementation help, refer to eBay API documentation"
+ },
+ "listingPolicies": {
+ "description": "This container sets listing policies that will be used to construct the listing. Listing policies include business policies, custom listing policies, and fields that override shipping costs, enable eBay Plus eligibility, or enable the Best Offer feature. This container is not initially required when creating an offer but will become required before the offer can be published. Busines policies (payment, return, fulfillment policies) will always be required before publishing an offer. Other policies, including the seller created compliance policies and seller created take-back policy, will be required as needed by the marketplace, category, or product.
This container is required for updating published offers, regardless of whether or not the business policies are being changed. For an unpublished offer, this field is not necessarily required, but will be required before an offer can be published.
It is required that the seller be opted in to Business Policies before being able to create live eBay listings through the Inventory API. Sellers can opt-in to Business Policies through My eBay or by using the Account API's optInToProgram call. Similarly, payment, return, and fulfillment business policies may be created/managed in My eBay or by using the business policy calls of the Account API.
Important!Publish offer note: This container and a few of its child fields (as noted below) are required before an offer can be published to create an active listing.
",
+ "$ref": "#/components/schemas/ListingPolicies"
+ },
+ "listingStartDate": {
+ "type": "string",
+ "description": "This field can be used with an unpublished offer if the seller wants to specify a time in the future that the listing will become active on eBay. The timestamp supplied in this field should be in UTC format, and it should be far enough in the future so that the seller will have enough time to publish the listing with the publishOffer method.
For example: 2023-05-30T19:08:00Z.
This field is optional, and it doesn't apply to offers where the corresponding listing is already active. If this field is not provided, the listing starts immediately after a successful publishOffer method."
+ },
+ "lotSize": {
+ "type": "integer",
+ "description": "This field is only applicable if the listing is a lot listing. A lot listing is a listing that has multiple quantity of the same item, such as four identical tires being sold as a single offer, or it can be a mixed lot of similar items, such as used clothing items or an assortment of baseball cards. Whether the lot listing involved identical items or a mixed lot, the integer value passed into this field is the total number of items in the lot. Lots can be used for auction and fixed-price listings.",
+ "format": "int32"
+ },
+ "merchantLocationKey": {
+ "type": "string",
+ "description": "The unique identifier of a merchant's inventory location (where the inventory item in the offer is located).
To get more information about inventory locations, the getInventoryLocations method can be used.br>
Note: This field is not initially required upon first creating an offer, but will become required before an offer can be published.
Max length: 36"
+ },
+ "pricingSummary": {
+ "description": "This container shows the listing price for the product offer, and if applicable, the settings for the Minimum Advertised Price and Strikethrough Pricing features. The Minimum Advertised Price feature is only available on the US site. Strikethrough Pricing is available on the US, eBay Motors, UK, Germany, Canada (English and French), France, Italy, and Spain sites.
This container is required for updating published offers, regardless of whether or not the pricing information is being changed or not. For an unpublished offer, this container is not necessarily required, but an offer price will be required before an offer can be published, and if a pricingSummary container already exists for an unpublished offer, it must be provided again, even if the values are not changing.
Important!Publish offer note: This container and its child container, price, are required before an offer can be published to create an active listing.
5, each buyer may purchase between one to five of these products, and the purchases can occur in one multiple-quantity purchase, or over multiple transactions. If a buyer attempts to purchase one or more of these products, and the cumulative quantity will take the buyer beyond the quantity limit, that buyer will be blocked from that purchase.
If this field currently exists for an unpublished or published offer, it should be provided again in an updateOffer call, even if the value is not changing.
",
+ "format": "int32"
+ },
+ "regulatory": {
+ "description": "This container is used by the seller to provide regulatory information.",
+ "$ref": "#/components/schemas/Regulatory"
+ },
+ "secondaryCategoryId": {
+ "type": "string",
+ "description": "The unique identifier for a secondary category. This field is applicable if the seller decides to list the item under two categories. Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. A fee may be charged when adding a secondary category to a listing.
Note: You cannot list US eBay Motors vehicles in two categories. However, you can list Parts & Accessories in two categories."
+ },
+ "storeCategoryNames": {
+ "type": "array",
+ "description": "This container is used if the seller would like to place the inventory item into one or two store categories that the seller has set up for their eBay store. The string value(s) passed in to this container will be the full path(s) to the store categories, as shown below:
\"storeCategoryNames\": [
\"/Fashion/Men/Shirts\",
\"/Fashion/Men/Accessories\" ],
If this field currently exists for an unpublished or published offer, it should be provided again in an updateOffer call, even if the eBay categories are not changing.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "tax": {
+ "description": "This container is only applicable and used if a sales tax table, a Value-Added Tax (VAT) rate, or a tax exception category code will be applied to the offer. Only Business Sellers can apply VAT to their listings. It is possible that the applyTax field will be included with a value of true, but a buyer's purchase will not involve sales tax. A sales tax rate must be set up in the seller's sales tax table for the buyer's state/tax jurisdiction in order for that buyer to be subject to sales tax. Sales tax rates for different jurisdictions can be added/modified in the Payment Preferences section of My eBay, or the seller can use the sales tax calls of the Account API.
If tax information currently exists for an unpublished or published offer, it should be provided again in an updateOffer call, even if none of the tax settings are changing.
See the Using a tax table help page for more information on setting up and using a sales tax table.",
+ "$ref": "#/components/schemas/Tax"
+ }
+ },
+ "description": "updateOffer call. Every field that is currently set with the unpublished/published offer must also be passed into the updateOffer call, even those fields whose values are not changing. Note that for published offers, a successful updateOffer call will actually update the active eBay listing with whatever changes were made."
+ },
+ "EbayOfferDetailsWithKeys": {
+ "type": "object",
+ "properties": {
+ "availableQuantity": {
+ "type": "integer",
+ "description": "This integer value sets the quantity of the inventory item (specified by the sku value) that will be available for purchase by buyers shopping on the eBay site specified in the marketplaceId field. Quantity must be set to 1 or more in order for the inventory item to be purchasable, but this field is not necessarily required, even for published offers, if the general quantity of the inventory item has already been set in the inventory item record.
For auction listings, this field should not be provided.
Note: The availableQuantity field if set here overrides the quantity field set in the inventory item. See the note in Offer fields for details.",
+ "format": "int32"
+ },
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay category that the product will be listed under. This field is not immediately required upon creating an offer, but will be required before publishing the offer.
Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. The seller passes in a query string like \"iPhone 6\", and category ID values for suggested categories are returned in the response.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Note: When listing in categoryID 173651 (Auto Performance Tuning Devices & Software), use of catalog products is required. For more information, see Tuning devices and software.
"
+ },
+ "charity": {
+ "description": "This container is used if the seller wishes to select a charitable organization that will receive a percentage of sale proceeds for each sale generated by the eBay listing. This container consists of the charityId field to identify the charitable organization, and the donationPercentage field that indicates the percentage of the sales proceeds that will be donated to the charitable organization for each sale. Both fields in this container are conditionally required for charitable listings.",
+ "$ref": "#/components/schemas/Charity"
+ },
+ "extendedProducerResponsibility": {
+ "description": "This container is used to provide the eco-participation fee for a product.
Use the getExtendedProducerResponsibilityPoliciesĀ method of theĀ Sell Metadata API to retrieve categories that support eco-participation fee for a specified marketplace.",
+ "$ref": "#/components/schemas/ExtendedProducerResponsibility"
+ },
+ "format": {
+ "type": "string",
+ "description": "This enumerated value indicates the listing format of the offer.
Supported values are FIXED_PRICE and AUCTION. For implementation help, refer to eBay API documentation"
+ },
+ "hideBuyerDetails": {
+ "type": "boolean",
+ "description": "This field is included and set to true if the seller wishes to create a private listing.
Sellers may want to use this option when they believe that a listing's potential bidders/buyers would not want their obfuscated user IDs (and feedback scores) exposed to other users."
+ },
+ "includeCatalogProductDetails": {
+ "type": "boolean",
+ "description": "This field indicates whether or not eBay product catalog details are applied to a listing. A value of true indicates the listing corresponds to the eBay product associated with the provided product identifier. The product identifier is provided in createOrReplaceInventoryItem.
Default: trueNote: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to true if omitted.
"
+ },
+ "listingDescription": {
+ "type": "string",
+ "description": "The text in this field is (published offers), or will become (unpublished offers) the description of the eBay listing. This field is not immediately required for an unpublished offer, but will be required before publishing the offer. Note that if the listingDescription field was omitted in the createOffer call for the offer, the offer entity should have picked up the text provided in the product.description field of the inventory item record, or if the inventory item is part of a group, the offer entity should have picked up the text provided in the description field of the inventory item group record.
HTML tags and markup can be used in listing descriptions, but each character counts toward the max length limit.
Note: To ensure that their short listing description is optimized when viewed on mobile devices, sellers should strongly consider using eBay's View Item description summary feature when listing their items. Keep in mind that the 'short' listing description is what prospective buyers first see when they view the listing on a mobile device. The 'full' listing description is also available to mobile users when they click on the short listing description, but the full description is not automatically optimized for viewing in mobile devices, and many users won't even drill down to the full description.
Using HTML div and span tag attributes, this feature allows sellers to customize and fully control the short listing description that is displayed to prospective buyers when viewing the listing on a mobile device. The short listing description on mobile devices is limited to 800 characters, and whenever the full listing description (provided in this field, in UI, or seller tool) exceeds this limit, eBay uses a special algorithm to derive the best possible short listing description within the 800-character limit. However, due to some short listing description content being removed, it is definitely not ideal for the seller, and could lead to a bad buyer experience and possibly to a Significantly not as described (SNAD) case, since the buyer may not get complete details on the item when viewing the short listing description. See the eBay help page for more details on using the HTML div and span tags.
Max length: 500000 (which includes HTML markup/tags)"
+ },
+ "listingDuration": {
+ "type": "string",
+ "description": "This field indicates the number of days that the listing will be active. For fixed-price listings, this value must be set to GTC, but auction listings support different listing durations.
The GTC (Good 'Til Cancelled) listings are automatically renewed each calendar month until the seller decides to end the listing.
Note: If the listing duration expires for an auction offer without a winning bidder, the listing then becomes available as a fixed-price offer and listing duration will be GTC.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
For implementation help, refer to eBay API documentation"
+ },
+ "listingPolicies": {
+ "description": "This container sets listing policies that will be used to construct the listing. Listing policies include business policies, custom listing policies, and fields that override shipping costs, enable eBay Plus eligibility, or enable the Best Offer feature. This container is not initially required when creating an offer but will become required before the offer can be published. Busines policies (payment, return, fulfillment policies) will always be required before publishing an offer. Other policies, including the seller created compliance policies and seller created take-back policy, will be required as needed by the marketplace, category, or product.
It is required that the seller be opted into Business Policies before being able to create live eBay listings through the Inventory API. Sellers can opt-in to Business Policies through My eBay or by using the Account API's optInToProgram call. Payment, return, and fulfillment listing policies may be created/managed in My eBay or by using the listing policy calls of the sell Account API. The sell Account API can also be used to create and manage custom policies. For more information, see the sell Account API.
Important!Publish offer note: This container and a few of its child fields (as noted below) are required before an offer can be published to create an active listing.
For example: 2023-05-30T19:08:00Z.
This field is optional. If this field is not provided, the listing starts immediately after a successful publishOffer method."
+ },
+ "lotSize": {
+ "type": "integer",
+ "description": "This field is only applicable if the listing is a lot listing. A lot listing is a listing that has multiple quantity of the same item, such as four identical tires being sold as a single offer, or it can be a mixed lot of similar items, such as used clothing items or an assortment of baseball cards. Whether the lot listing involved identical items or a mixed lot, the integer value passed into this field is the total number of items in the lot. Lots can be used for auction and fixed-price listings.",
+ "format": "int32"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "This enumeration value is the unique identifier of the eBay site for which the offer will be made available. See MarketplaceEnum for the list of supported enumeration values. This field is required. For implementation help, refer to eBay API documentation"
+ },
+ "merchantLocationKey": {
+ "type": "string",
+ "description": "The unique identifier of a merchant's inventory location (where the inventory item in the offer is located).
To get more information about inventory locations, the getInventoryLocations method can be used.
Note: This field is not initially required upon first creating an offer, but will become required before an offer can be published.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max length: 36"
+ },
+ "pricingSummary": {
+ "description": "This container shows the listing price for the product offer, and if applicable, the settings for the Minimum Advertised Price and Strikethrough Pricing features. The Minimum Advertised Price feature is only available on the US site. Strikethrough Pricing is available on the US, eBay Motors, UK, Germany, Canada (English and French), France, Italy, and Spain sites.
This container is not initially required upon first creating an offer, but the price of the offer will become required before an offer can be published.
Important!Publish offer note: This container and its child container, price, are required before an offer can be published to create an active listing.
5, each buyer may purchase between one to five of these products, and the purchases can occur in one multiple-quantity purchase, or over multiple transactions. If a buyer attempts to purchase one or more of these products, and the cumulative quantity will take the buyer beyond the quantity limit, that buyer will be blocked from that purchase.
",
+ "format": "int32"
+ },
+ "regulatory": {
+ "description": "This container is used by the seller to provide regulatory information.",
+ "$ref": "#/components/schemas/Regulatory"
+ },
+ "secondaryCategoryId": {
+ "type": "string",
+ "description": "The unique identifier for a secondary category. This field is applicable if the seller decides to list the item under two categories. Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. A fee may be charged when adding a secondary category to a listing.
Note: You cannot list US eBay Motors vehicles in two categories. However, you can list Parts & Accessories in two categories.Note: When listing in categoryID 173651 (Auto Performance Tuning Devices & Software), use of catalog products is required. For more information, see Tuning devices and software.
"
+ },
+ "sku": {
+ "type": "string",
+ "description": "The seller-defined SKU value of the product that will be listed on the eBay site (specified in the marketplaceId field). Only one offer (in unpublished or published state) may exist for each sku/marketplaceId/format combination. This field is required.
Use the getInventoryItems method to retrieve SKU values.
Max Length: 50
"
+ },
+ "storeCategoryNames": {
+ "type": "array",
+ "description": "This container is used if the seller would like to place the inventory item into one or two eBay store categories that the seller has set up for their eBay store. The string value(s) passed in to this container will be the full path(s) to the eBay store categories, as shown below:
\"storeCategoryNames\": [
\"/Fashion/Men/Shirts\",
\"/Fashion/Men/Accessories\" ],
",
+ "items": {
+ "type": "string"
+ }
+ },
+ "tax": {
+ "description": "This container is applicable and used only if a sales-tax table, a Value-Added Tax (VAT) rate, or a tax exception category code will be applied to the offer. Only Business Sellers can apply VAT to their listings. It is possible that the applyTax field will be included with a value of true, but a buyer's purchase will not involve sales tax.
A sales-tax rate must be set up in the seller's sales-tax table for the buyer's state/tax jurisdiction in order for that buyer to be subject to sales tax. Sales-tax rates for different jurisdictions can be added/modified in the Payment Preferences section of My eBay, or the seller can use the sales tax calls of the Account API.
Note: Sales-tax tables are available only for the US and Canada marketplaces.Refer to Taxes and import charges for more information on setting up and using a sales tax table.",
+ "$ref": "#/components/schemas/Tax"
+ }
+ },
+ "description": "This type provides details of an offer, and is used by the base request payload of the createOffer and bulkCreateOffer methods."
+ },
+ "EnergyEfficiencyLabel": {
+ "type": "object",
+ "properties": {
+ "imageDescription": {
+ "type": "string",
+ "description": "A brief verbal summary of the information included on the Energy Efficiency Label for an item.
For example, On a scale of A to G the rating is E."
+ },
+ "imageURL": {
+ "type": "string",
+ "description": "The URL to the Energy Efficiency Label image that is applicable to an item."
+ },
+ "productInformationSheet": {
+ "type": "string",
+ "description": "The URL to the Product Information Sheet that provides complete manufacturer-provided efficiency information about an item."
+ }
+ },
+ "description": "This type provides information about the energy efficiency for certain durable goods.
Important! When providing energy efficiency information on an appliance or smartphones and tablets listing, the energy efficiency rating and range of the item must be specified through the the aspects field when creating the inventory item record. Use the getItemAspectsForCategory method of the Taxonomy API to retrieve applicable rating and range values for a specified category.
Note: 0 should not be used as a default value.Minimum: 0.0",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "producerProductId": {
+ "type": "string",
+ "description": "Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on."
+ },
+ "productDocumentationId": {
+ "type": "string",
+ "description": "Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on."
+ },
+ "productPackageId": {
+ "type": "string",
+ "description": "Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on."
+ },
+ "shipmentPackageId": {
+ "type": "string",
+ "description": "Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on."
+ }
+ },
+ "description": "This type provides IDs for the producer or importer related to the new item, packaging, added documentation, or an eco-participation fee. In some markets, such as in France, this may be the importer of the item."
+ },
+ "Fee": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "This dollar value in this container is the actual dollar value of the listing fee type specified in the feeType field.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "feeType": {
+ "type": "string",
+ "description": "The value returned in this field indicates the type of listing fee that the seller may incur if one or more unpublished offers (offers are specified in the call request) are published on the marketplace specified in the marketplaceId field. Applicable listing fees will often include things such as InsertionFee or SubtitleFee, but many fee types will get returned even when they are 0.0.
See the Standard selling fees help page for more information on listing fees."
+ },
+ "promotionalDiscount": {
+ "description": "The dollar value in this container indicates any eBay promotional discount applied toward the listing fee type specified in the feeType field. If there was no discount applied toward the fee, this container is still returned but its value is 0.0.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type is used to express expected listing fees that the seller may incur for one or more unpublished offers, as well as any eBay-related promotional discounts being applied toward a specific fee. These fees are the expected cumulative fees per eBay marketplace (which is indicated in the marketplaceId field)."
+ },
+ "FeeSummary": {
+ "type": "object",
+ "properties": {
+ "fees": {
+ "type": "array",
+ "description": "This container is an array of listing fees that can be expected to be applied to an offer on the specified eBay marketplace (marketplaceId value). Many fee types will get returned even when they are 0.0.
See the Standard selling fees help page for more information on listing fees.",
+ "items": {
+ "$ref": "#/components/schemas/Fee"
+ }
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "This is the unique identifier of the eBay site for which listing fees for the offer are applicable. For implementation help, refer to eBay API documentation"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "This container will contain an array of errors and/or warnings when a call is made, and errors and/or warnings occur.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type is used to display the expected listing fees for each unpublished offer specified in the request of the getListingFees call."
+ },
+ "FeesSummaryResponse": {
+ "type": "object",
+ "properties": {
+ "feeSummaries": {
+ "type": "array",
+ "description": "This container consists of an array of one or more listing fees that the seller can expect to pay for unpublished offers specified in the call request. Many fee types will get returned even when they are 0.0.",
+ "items": {
+ "$ref": "#/components/schemas/FeeSummary"
+ }
+ }
+ },
+ "description": "This type is used by the base response payload for the getListingFees call. "
+ },
+ "FormatAllocation": {
+ "type": "object",
+ "properties": {
+ "auction": {
+ "type": "integer",
+ "description": "This integer value indicates the quantity of the inventory item that is reserved for the published auction format offers of the SKU.",
+ "format": "int32"
+ },
+ "fixedPrice": {
+ "type": "integer",
+ "description": "This integer value indicates the quantity of the inventory item that is available for the fixed-price offers of the SKU.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used to indicate the quantities of the inventory items that are reserved for the different listing formats of the SKU offers."
+ },
+ "FulfillmentCenterSpecifications": {
+ "type": "object",
+ "properties": {
+ "sameDayShippingCutOffTimes": {
+ "description": "Note: This container only applies to listings with same-day handling.
This container specifies cut-off time(s) for order handling (and optionally cut-off overrides) at a fulfillment center location.
For example, if the cut-off time for order handling is 14:00, any orders made after this time will be handled on the next available business day.
Note: Shipping cut-off times must be specified if one of the locationTypes of the inventory location is FULFILLMENT_CENTER.",
+ "$ref": "#/components/schemas/SameDayShippingCutOffTimes"
+ }
+ },
+ "description": "This type is used to provide shipping specification details, such as the weekly cut-off schedule for order handling and cut-off override(s), for a fulfillment center location. "
+ },
+ "GeoCoordinates": {
+ "type": "object",
+ "properties": {
+ "latitude": {
+ "type": "number",
+ "description": "The latitude (North-South) component of the geographic coordinate. This field is required if a geoCoordinates container is used.
This field is returned if geographical coordinates are set for the location.
Example: 33.089805"
+ },
+ "longitude": {
+ "type": "number",
+ "description": "The longitude (East-West) component of the geographic coordinate. This field is required if a geoCoordinates container is used.
This field is returned if geographical coordinates are set for the location.
Example: -88.709822"
+ }
+ },
+ "description": "This type is used to express the Global Positioning System (GPS) latitude and longitude coordinates of an inventory location."
+ },
+ "GetInventoryItem": {
+ "type": "object",
+ "properties": {
+ "sku": {
+ "type": "string",
+ "description": "An array of SKU values are passed in under the sku container to retrieve up to 25 inventory item records.
Use the getInventoryItems method to retrieve SKU values."
+ }
+ },
+ "description": "The seller-defined Stock-Keeping Unit (SKU) of each inventory item that the user wants to retrieve is passed in the request of the bulkGetInventoryItem method."
+ },
+ "GetInventoryItemResponse": {
+ "type": "object",
+ "properties": {
+ "errors": {
+ "type": "array",
+ "description": "This container will be returned if there were one or more errors associated with retrieving the inventory item record.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "inventoryItem": {
+ "description": "This container consists of detailed information on the inventory item specified in the sku field.",
+ "$ref": "#/components/schemas/InventoryItemWithSkuLocaleGroupKeys"
+ },
+ "sku": {
+ "type": "string",
+ "description": "The seller-defined Stock-Keeping Unit (SKU) of the inventory item. The seller should have a unique SKU value for every product that they sell."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "The HTTP status code returned in this field indicates the success or failure of retrieving the inventory item record for the inventory item specified in the sku field. See the HTTP status codes table to see which each status code indicates.",
+ "format": "int32"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "This container will be returned if there were one or more warnings associated with retrieving the inventory item record.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type is used by the response of the bulkGetInventoryItem method to give the status of each inventory item record that the user tried to retrieve."
+ },
+ "Hazmat": {
+ "type": "object",
+ "properties": {
+ "component": {
+ "type": "string",
+ "description": "This field is used by the seller to provide component information for the listing. For example, component information can provide the specific material of Hazmat concern.
Max length: 120"
+ },
+ "pictograms": {
+ "type": "array",
+ "description": "An array of comma-separated string values listing applicable pictogram code(s) for Hazard Pictogram(s).
If your product contains hazardous substances or mixtures, please select the values corresponding to the hazard pictograms that are stated on your product's Safety Data Sheet. The selected hazard information will be displayed on your listing.
Note: Use the getHazardousMaterialsLabels method in the Metadata API to find supported values for a specific marketplace/site. Refer to Pictogram sample values for additional information.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "signalWord": {
+ "type": "string",
+ "description": "This field sets the signal word for hazardous materials in the listing.
If your product contains hazardous substances or mixtures, please select a value corresponding to the signal word that is stated on your product's Safety Data Sheet. The selected hazard information will be displayed on your listing.
Note: Use the getHazardousMaterialsLabels method in the Metadata API to find supported values for a specific marketplace/site. Refer to Signal word information for additional information."
+ },
+ "statements": {
+ "type": "array",
+ "description": "An array of comma-separated string values specifying applicable statement code(s) for hazard statement(s) for the listing.
If your product contains hazardous substances or mixtures, please select the values corresponding to the hazard statements that are stated on your product's Safety Data Sheet. The selected hazard information will be displayed on your listing.
Note: Use the getHazardousMaterialsLabels method in the Metadata API to find supported values for a specific marketplace/site. Refer to Hazard statement sample values for additional information.
This field is required if hazardous material information is provided for the listing.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This container is used by the seller to provide hazardous material information for the listing.
The statements element is required to complete the hazmat section of a listing.
The following elements are optional:- pictograms
- signalWord
- component
"
+ },
+ "Interval": {
+ "type": "object",
+ "properties": {
+ "close": {
+ "type": "string",
+ "description": "The close value is actually the time that the store location closes. Local time (in Military format) is used. So, if a store closed at 8 PM local time, the close time would look like the following: 20:00:00. This field is conditionally required if the intervals container is used to specify working hours or special hours for a store.
This field is returned if set for the store location."
+ },
+ "open": {
+ "type": "string",
+ "description": "The open value is actually the time that the store opens. Local time (in Military format) is used. So, if a store opens at 9 AM local time, the open time would look like the following: 09:00:00. This field is conditionally required if the intervals container is used to specify working hours or special hours for a store.
This field is returned if set for the store location."
+ }
+ },
+ "description": "This type is used by the intervals container to define the opening and closing times of a store location's working day. Local time (in Military format) is used, with the following format: hh:mm:ss."
+ },
+ "InventoryItem": {
+ "type": "object",
+ "properties": {
+ "availability": {
+ "description": "This container is used to specify the quantity of the inventory item that are available for purchase.
This container is optional up until the seller is ready to publish an offer with the SKU, at which time it becomes required. Availability data must also be passed if an inventory item is being updated and availability data already exists for that inventory item.
Since an inventory item must have specified quantity before being published in an offer, this container is always returned in the 'Get' calls for SKUs that are part of a published offer. If a SKU is not part of a published offer, this container will only be returned if set for the inventory item.",
+ "$ref": "#/components/schemas/Availability"
+ },
+ "condition": {
+ "type": "string",
+ "description": "This enumeration value indicates the condition of the item. Supported item condition values will vary by eBay site and category. To see which item condition values that a particular eBay category supports, use the getItemConditionPolicies method of the Metadata API. This method returns condition ID values that map to the enumeration values defined in the ConditionEnum type. The Item condition ID and name values topic in the Selling Integration Guide has a table that maps condition ID values to ConditionEnum values. The getItemConditionPolicies call reference page has more information.
A condition value is optional up until the seller is ready to publish an offer with the SKU, at which time it becomes required for most eBay categories.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
NEW, LIKE_NEW, NEW_OTHER, or NEW_WITH_DEFECTS.
The conditionDescription field is available for all eBay categories. If the conditionDescription field is used with an item in one of the new conditions (mentioned in previous paragraph), eBay will simply ignore this field if included, and eBay will return a warning message to the user.
This field should only be used to further clarify the condition of the used item. It should not be used for branding, promotions, shipping, returns, payment or other information unrelated to the condition of the used item. Make sure that the condition value, condition description, listing description, and the item's pictures do not contradict one another.
This field is not always required, but is required if an inventory item is being updated and a condition description already exists for that inventory item.
This field is returned in the getInventoryItem and getInventoryItems calls if a condition description was provided for a used inventory item.
Max Length: 1000."
+ },
+ "conditionDescriptors": {
+ "type": "array",
+ "description": "This container is used by the seller to provide additional information about the condition of an item in a structured format. Condition descriptors are name-value attributes that can be either closed set or open text inputs.
For trading card and coin listings in applicable categories, sellers must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition to specify the item as Graded or Ungraded, respectively. Use of either of these conditions requires the seller to use this array to provide one or more applicable Condition Descriptor name-value pairs.
To retrieve all condition descriptor numeric IDs for a category, use the getItemConditionPolicies method of the Metadata API.",
+ "items": {
+ "$ref": "#/components/schemas/ConditionDescriptor"
+ }
+ },
+ "packageWeightAndSize": {
+ "description": "This container is used if the seller is offering one or more calculated shipping options for the inventory item, or if the seller is offering flat-rate shipping but is including a shipping surcharge based on the item's weight. This container is used to specify the dimensions and weight of a shipping package.
Note: Package weight and dimensions are only supported for the following marketplaces: AU, CA, DE, IT, UK, US, and Motors. If this information is provided on other marketplaces, it will be ignored.
This container is not always required, but is required if an inventory item is being updated and shipping package data already exists for that inventory item.
This container is returned in the getInventoryItem and getInventoryItems calls if package type, package weight, and/or package dimensions are specified for an inventory item.
See the Calculated shipping help page for more information on calculated shipping.",
+ "$ref": "#/components/schemas/PackageWeightAndSize"
+ },
+ "product": {
+ "description": "This container is used to define the product details, such as product title, product description, product identifiers (eBay Product ID, GTIN, or Brand/MPN pair), product aspects/item specifics, and product images. Note that an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) value can be used in an attempt to find a matching product in the eBay Catalog. If a product match is found, the inventory item record will automatically pick up all product details associated with the eBay Catalog product.
Many eBay categories will require at least one product identifier (a GTIN or a Brand/MPN pair). To discover which product identifier(s) that an eBay category might require or support, use the getItemAspectsForCategory method in the Taxonomy API. In the getItemAspectsForCategory response, look for product identifier names (brand, mpn, upc, ean, isbn) in the localizedAspectName fields, and then look for the correspondinng aspectRequired boolean fields as well as the corresponding aspectUsage field, which will indicate if the aspect is required, recommended, or optional. In some cases, a product identifier type may be required, but not known/applicable for a product. If this is the case, the seller must still include the corresponding field in the inventory item record, but pass in a default text string. This text string can vary by site, so the seller should use the GeteBayDetails call of the Trading API to get this string value. In the GeteBayDetails call, the seller should include a DetailName field with its value set to ProductDetails. In the response of the call, the seller can see the default string value in the ProductDetails.ProductIdentifierUnavailableText field. The seller will use this value in one or more of the product identifier fields (ean, isbn, upc, or mpn) if a product ID isn't known or applicable.
This container is not initially required, but it is required before an inventory item can be published as an offer, and/or if an inventory item is being updated and product data already exists for that inventory item.
This container is always returned for published offers in the getInventoryItem, bulkGetInventoryItem, and getInventoryItems calls since product data must be defined for published offers, but for unpublished inventory items, this container will only be returned if product details have been defined for the inventory item.
Important!Publish offer note: This container and a few of its child fields (as noted below) are required before an offer can be published to create an active listing.
Important! Effective from December 28th, 2024, sellers offering certain rechargeable devices in EU and Northern Ireland markets must comply with the Common Charger Directive (CCD) and list appropriate charger-related aspects and values on their listings. See Common Charger Directive for more information.
Below is an example of the proper JSON syntax to use when manually inputting item specifics. Note that one item specific name, such as 'Features', can have more than one value. If an item specific name has more than one value, each value is delimited with a comma.
\"aspects\": {
\"pattern\": [\"solid\"],
\"sleeves\": [\"short\"]
}
This container is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Note: Since this description will ultimately become the listing description in a multiple-variation listing, the seller should omit the listingDescription field when creating the offers for each variation. If they include the listingDescription field for the individual offer(s) in an item group, the text in that field for a published offer will overwrite the text provided in this description field for the inventory item group.
HTML tags and markup can be used in this field, but each character counts toward the max length limit.
Note: To ensure that their short listing description is optimized when viewed on mobile devices, sellers should strongly consider using eBay's View Item description summary feature when listing their items. Keep in mind that the 'short' listing description is what prospective buyers first see when they view the listing on a mobile device. The 'full' listing description is also available to mobile users when they click on the short listing description, but the full description is not automatically optimized for viewing in mobile devices, and many users won't even drill down to the full description.
Using HTML div and span tag attributes, this feature allows sellers to customize and fully control the short listing description that is displayed to prospective buyers when viewing the listing on a mobile device. The short listing description on mobile devices is limited to 800 characters, and whenever the full listing description (provided in this field, in UI, or seller tool) exceeds this limit, eBay uses a special algorithm to derive the best possible short listing description within the 800-character limit. However, due to some short listing description content being removed, it is definitely not ideal for the seller, and could lead to a bad buyer experience and possibly to a Significantly not as described (SNAD) case, since the buyer may not get complete details on the item when viewing the short listing description. See the eBay help page for more details on using the HTML div and span tags.
This field is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length: 500000 (which includes HTML markup/tags)
"
+ },
+ "imageUrls": {
+ "type": "array",
+ "description": "An array of one or more links to images for the inventory item group. URLs must use the \"HTTPS\" protocol. Images can be self-hosted by the seller, or sellers can use the UploadSiteHostedPictures call of the Trading API to upload images to an eBay Picture Server. If successful, the response of the UploadSiteHostedPictures call will contain a full URL to the image on an eBay Picture Server. This is the URL that will be passed in through the imageUrls array.
Note: Before any offer can be published, at least one image must exist for the offer. Links to images can either be passed in through this imageUrls container, or they can be passed in through the product.imageUrls container when creating each inventory item in the group. If the variesBy.aspectsImageVariesBy field is used to specify the main product aspect where the variations vary, the links to the images must be passed in through this imageUrls container, and there should be a picture for each variation. So, if the variesBy.aspectsImageVariesBy field is set to Color, a link should be included to an image demonstrating each available color in the group.
In almost any category at no cost, sellers can include up to 24 pictures in one listing. For inventory items that are a part of an inventory item group/multiple-variation listings, a maximum of 12 pictures may be used per inventory item in the group. Motor vehicle listings are an exception. The number of included pictures in motor vehicle listings depend on the selected vehicle package (see Fees for selling vehicles on eBay Motors).
This container will always be returned for an inventory item group that has at least one published offer since a published offer will always have at least one picture, but this container will only be returned if defined for inventory item groups that have yet to have any published offers. ",
+ "items": {
+ "type": "string"
+ }
+ },
+ "inventoryItemGroupKey": {
+ "type": "string",
+ "description": "This is the unique identifier of the inventory item group. This identifier is created by the seller when an inventory item group is created.
Note: This field is only applicable to the getInventoryItemGroup call and not to the createOrReplaceInventoryItemGroup call. In the createOrReplaceInventoryItemGroup call, the inventoryItemGroupKey value is passed into the end of the call URI instead. "
+ },
+ "subtitle": {
+ "type": "string",
+ "description": "A subtitle is an optional listing feature that allows the seller to provide more information about the product, possibly including keywords that may assist with search results. An additional listing fee will be charged to the seller if a subtitle is used. For more information on using listing subtitles on the US site, see the Adding a subtitle to your listings help page.
Note: Since this subtitle will ultimately become the subtitle in a multiple-variation listing, the seller should not include the subtitle field when creating the inventory items that are members of the group. If they do include the subtitle field in an inventory item record, the text in that field will overwrite the text provided in this subtitle field for each inventory item in the group that is published.
This field will only be returned if set for an inventory item.
Max Length: 55
"
+ },
+ "title": {
+ "type": "string",
+ "description": "The title of the inventory item group. This title will ultimately become the listing title once the first offer of the group is published. This field is not initially required when first creating an inventory item group, but will be required before the first offer of the group is published.
Note: Since this title will ultimately become the listing title in a multiple-variation listing, the seller should omit the title field when creating the inventory items that are members of the group. If they do include the title field in an inventory item record, the text in that field will overwrite the text provided in this title field for each inventory item in the group that is published.
This field is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length: 80
"
+ },
+ "variantSKUs": {
+ "type": "array",
+ "description": "This required container is used to assign individual inventory items to the inventory item group. Multiple SKU values are passed in to this container. If updating an existing inventory item group, the seller should make sure that all member SKU values are passed in, as long as the seller wants that SKU to remain in the group.
It is also possible to add or remove SKUs with a createOrReplaceInventoryItemGroup call. If the seller wants to remove a SKU from the group, that seller will just omit that SKU value from this container to remove that inventory item/SKU from the inventory item group and any published, multiple-variation listing. However, a variation cannot be removed from the group if that variation has one or more sales for that listing. A workaround for this is to set that variation's quantity to 0 and it will be 'grayed out' in the View Item page.
This container is always returned.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "variesBy": {
+ "description": "This container is used to specify product aspects for which variations within an inventory item group vary, and a complete list of all those variances. For example, t-shirts in an inventory item group may be available in multiple sizes and colors. If this is the case, Color and Size would both be values in the specifications.name fields, and the available colors and sizes would be values under the corresponding specifications.values array. If the seller will be including multiple images in the listing that will demonstrate how each variation differs, that seller will also include the aspectsImageVariesBy field, and call out the product aspect where the listing images differ. In the t-shirts example, this product aspect would be Color, and the seller could either include URLs to images of the t-shirt (in available colors) through the inventory item group entity, or the seller could also included URLs to images of the t-shirt through the individual inventory item entities of the group.
This container is not initially required when first creating an inventory item group, but the variesBy.specifications container will be required before the first offer of the group is published.
This container is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.
Important!Publish offer note: This container and its child fields (as noted below) are required before an offer can be published to create an active listing.
For information on supported marketplaces and platforms, as well as other requirements and limitations of video support, please refer to Managing videos.
Note: Only one video per listing is supported.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This type is used by the base request payload of the createOrReplaceInventoryItemGroup call and the base response payload of the getInventoryItemGroup call."
+ },
+ "InventoryItemListing": {
+ "type": "object",
+ "properties": {
+ "offerId": {
+ "type": "string",
+ "description": "Upon a successful migration of a listing, eBay auto-generates this unique identifier, and this offer ID value will be used to retrieve and manage the newly-created offer object. This value will only be generated and returned if the eBay listing is migrated successfully."
+ },
+ "sku": {
+ "type": "string",
+ "description": "This is the seller-defined SKU value associated with the item(s) in a listing. This same SKU value will be used to retrieve and manage the newly-created inventory item object if the listing migration is successful. This SKU value will get returned even if the migration is not successful."
+ }
+ },
+ "description": "This type is used by the inventoryItems container that is returned in the response of the bulkMigrateListing call. Up to five sku/offerId pairs may be returned under the inventoryItems container, dependent on how many eBay listings the seller is attempting to migrate to the inventory model."
+ },
+ "InventoryItemResponse": {
+ "type": "object",
+ "properties": {
+ "errors": {
+ "type": "array",
+ "description": "This container will be returned if there were one or more errors associated with the creation or update to the inventory item record.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "locale": {
+ "type": "string",
+ "description": "This field returns the natural language that was provided in the field values of the request payload (i.e., en_AU, en_GB or de_DE). For implementation help, refer to eBay API documentation"
+ },
+ "sku": {
+ "type": "string",
+ "description": "The seller-defined Stock-Keeping Unit (SKU) of the inventory item. The seller should have a unique SKU value for every product that they sell."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "The HTTP status code returned in this field indicates the success or failure of creating or updating the inventory item record for the inventory item indicated in the sku field. See the HTTP status codes table to see which each status code indicates.",
+ "format": "int32"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "This container will be returned if there were one or more warnings associated with the creation or update to the inventory item record.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type is used by the response of the bulkCreateOrReplaceInventoryItem method to indicate the success or failure of creating and/or updating each inventory item record. The sku value in this type identifies each inventory item record."
+ },
+ "InventoryItemWithSkuLocale": {
+ "type": "object",
+ "properties": {
+ "availability": {
+ "description": "This container is used to specify the quantity of the inventory item that are available for purchase.
Availability data must also be passed if an inventory item is being updated and availability data already exists for that inventory item.
Since an inventory item must have specified quantity before being published in an offer, this container is always returned in the 'Get' calls for SKUs that are part of a published offer. If a SKU is not part of a published offer, this container will only be returned if set for the inventory item. ",
+ "$ref": "#/components/schemas/Availability"
+ },
+ "condition": {
+ "type": "string",
+ "description": "This enumeration value indicates the condition of the item. Supported item condition values will vary by eBay site and category. To see which item condition values that a particular eBay category supports, use the getItemConditionPolicies method of the Metadata API. This method returns condition ID values that map to the enumeration values defined in the ConditionEnum type. The Item condition ID and name values topic in the Selling Integration Guide has a table that maps condition ID values to ConditionEnum values. The getItemConditionPolicies call reference page has more information.
A condition value is optional up until the seller is ready to publish an offer with the SKU, at which time it becomes required for most eBay categories.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
NEW, LIKE_NEW, NEW_OTHER, or NEW_WITH_DEFECTS.
The conditionDescription field is available for all eBay categories. If the conditionDescription field is used with an item in one of the new conditions (mentioned in previous paragraph), eBay will simply ignore this field if included, and eBay will return a warning message to the user.
This field should only be used to further clarify the condition of the used item. It should not be used for branding, promotions, shipping, returns, payment or other information unrelated to the condition of the used item. Make sure that the condition value, condition description, listing description, and the item's pictures do not contradict one another.
This field is not always required, but is required if an inventory item is being updated and a condition description already exists for that inventory item.
This field is returned in the getInventoryItem, bulkGetInventoryItem, and getInventoryItems calls if a condition description was provided for a used inventory item.
Max Length: 1000"
+ },
+ "conditionDescriptors": {
+ "type": "array",
+ "description": "This container is used by the seller to provide additional information about the condition of an item in a structured format. Condition descriptors are name-value attributes that can be either closed set or open text inputs.
For trading card and coin listings in applicable categories, sellers must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition to specify the item as Graded or Ungraded, respectively. Use of either of these conditions requires the seller to use this array to provide one or more applicable Condition Descriptor name-value pairs.
To retrieve all condition descriptor numeric IDs for a category, use the getItemConditionPolicies method of the Metadata API.",
+ "items": {
+ "$ref": "#/components/schemas/ConditionDescriptor"
+ }
+ },
+ "locale": {
+ "type": "string",
+ "description": "This request parameter sets the natural language that was provided in the field values of the request payload (i.e., en_AU, en_GB or de_DE). For implementation help, refer to eBay API documentation"
+ },
+ "packageWeightAndSize": {
+ "description": "This container is used if the seller is offering one or more calculated shipping options for the inventory item, or if the seller is offering flat-rate shipping but is including a shipping surcharge based on the item's weight. This container is used to specify the dimensions and weight of a shipping package.
Note: Package weight and dimensions are only supported for the following marketplaces: AU, CA, DE, IT, UK, US, and Motors. If this information is provided on other marketplaces, it will be ignored.
This container is not always required, but is required if an inventory item is being updated and shipping package data already exists for that inventory item.
This container is returned in the getInventoryItem, bulkGetInventoryItem, and getInventoryItems calls if package type, package weight, and/or package dimensions are specified for an inventory item.
See the Calculated shipping help page for more information on calculated shipping.",
+ "$ref": "#/components/schemas/PackageWeightAndSize"
+ },
+ "product": {
+ "description": "This container is used to define the product details, such as product title, product description, product identifiers (eBay Product ID, GTIN, or Brand/MPN pair), product aspects/item specifics, and product images. Note that an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) value can be used in an attempt to find a matching product in the eBay Catalog. If a product match is found, the inventory item record will automatically pick up all product details associated with the eBay Catalog product.
Many eBay categories will require at least one product identifier (a GTIN or a Brand/MPN pair). To discover which product identifier(s) that an eBay category might require or support, use the getItemAspectsForCategory method in the Taxonomy API. In the getItemAspectsForCategory response, look for product identifier names (brand, mpn, upc, ean, isbn) in the localizedAspectName fields, and then look for the correspondinng aspectRequired boolean fields as well as the corresponding aspectUsage field, which will indicate if the aspect is required, recommended, or optional. In some cases, a product identifier type may be required, but not known/applicable for a product. If this is the case, the seller must still include the corresponding field in the inventory item record, but pass in a default text string. This text string can vary by site, so the seller should use the GeteBayDetails call of the Trading API to get this string value. In the GeteBayDetails call, the seller should include a DetailName field with its value set to ProductDetails. In the response of the call, the seller can see the default string value in the ProductDetails.ProductIdentifierUnavailableText field. The seller will use this value in one or more of the product identifier fields (ean, isbn, upc, or mpn) if a product ID isn't known or applicable.
This container is not initially required, but it is required before an inventory item can be published as an offer, and/or if an inventory item is being updated and product data already exists for that inventory item.
This container is always returned for published offers in the getInventoryItem, bulkGetInventoryItem, and getInventoryItems calls since product data must be defined for published offers, but for unpublished inventory items, this container will only be returned if product details have been defined for the inventory item.
Important!Publish offer note: This container and a few of its child fields (as noted below) are required before an offer can be published to create an active listing.
Max Length: 50
"
+ }
+ },
+ "description": "This type is used to define/modify each inventory item record that is being created and/or updated with the bulkCreateOrReplaceInventoryItem method. Up to 25 inventory item records can be created and/or updated with one call."
+ },
+ "InventoryItemWithSkuLocaleGroupKeys": {
+ "type": "object",
+ "properties": {
+ "availability": {
+ "description": "This container shows the quantity of the inventory item that is available for purchase if the item will be shipped to the buyer, and/or the quantity of the inventory item that is available for In-Store Pickup at one or more of the merchant's physical stores.",
+ "$ref": "#/components/schemas/AvailabilityWithAll"
+ },
+ "condition": {
+ "type": "string",
+ "description": "This enumeration value indicates the condition of the item. Supported item condition values will vary by eBay site and category.
Since the condition of an inventory item must be specified before being published in an offer, this field is always returned in the 'Get' calls for SKUs that are part of a published offer. If a SKU is not part of a published offer, this field will only be returned if set for the inventory item. For implementation help, refer to eBay API documentation"
+ },
+ "conditionDescription": {
+ "type": "string",
+ "description": "This string field is used by the seller to more clearly describe the condition of used items, or items that are not 'Brand New', 'New with tags', or 'New in box'. The ConditionDescription field is available for all categories. If the ConditionDescription field is used with an item in a new condition (Condition IDs 1000-1499), eBay will simply ignore this field if included, and eBay will return a warning message to the user. This field should only be used to further clarify the condition of the used item. It should not be used for branding, promotions, shipping, returns, payment or other information unrelated to the condition of the item. Make sure that the condition value, condition description, listing description, and the item's pictures do not contradict one another.Max length: 1000."
+ },
+ "conditionDescriptors": {
+ "type": "array",
+ "description": "This container is used by the seller to provide additional information about the condition of an item in a structured format. Condition descriptors are name-value attributes that can be either closed set or open text inputs.
For trading card and coin listings in applicable categories, sellers must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition to specify the item as Graded or Ungraded, respectively. Use of either of these conditions requires the seller to use this array to provide one or more applicable Condition Descriptor name-value pairs.
To retrieve all condition descriptor numeric IDs for a category, use the getItemConditionPolicies method of the Metadata API.",
+ "items": {
+ "$ref": "#/components/schemas/ConditionDescriptor"
+ }
+ },
+ "inventoryItemGroupKeys": {
+ "type": "array",
+ "description": "This array is returned if the inventory item is associated with any inventory item group(s). The value(s) returned in this array are the unique identifier(s) of the inventory item's variation in a multiple-variation listing. This array is not returned if the inventory item is not associated with any inventory item groups.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "locale": {
+ "type": "string",
+ "description": "This field returns the natural language that was provided in the field values of the request payload (i.e., en_AU, en_GB or de_DE). For implementation help, refer to eBay API documentation"
+ },
+ "packageWeightAndSize": {
+ "description": "This container is used to specify the dimensions and weight of a shipping package.",
+ "$ref": "#/components/schemas/PackageWeightAndSize"
+ },
+ "product": {
+ "description": "This container is used in a createOrReplaceInventoryItem call to pass in a Global Trade Item Number (GTIN) or a Brand and Manufacturer Part Number (MPN) pair to identify a product to be matched with a product in the eBay catalog. If a match is found in the eBay product catalog, the inventory item is automatically populated with available product details such as a title, a subtitle, a product description, item specifics, and links to stock images for the product.",
+ "$ref": "#/components/schemas/Product"
+ },
+ "sku": {
+ "type": "string",
+ "description": "The seller-defined Stock-Keeping Unit (SKU) of the inventory item. The seller should have a unique SKU value for every product that they sell."
+ }
+ },
+ "description": "This type is used to provide details about each retrieved inventory item record."
+ },
+ "InventoryItemWithSkuLocaleGroupid": {
+ "type": "object",
+ "properties": {
+ "availability": {
+ "description": "This container is used to specify the quantity of the inventory item that are available for purchase if the item will be shipped to the buyer, and the quantity of the inventory item that are available for In-Store Pickup at one or more of the merchant's physical stores",
+ "$ref": "#/components/schemas/AvailabilityWithAll"
+ },
+ "condition": {
+ "type": "string",
+ "description": "This enumeration value indicates the condition of the item. Supported item condition values will vary by eBay site and category.
Since the condition of an inventory item must be specified before being published in an offer, this field is always returned in the 'Get' calls for SKUs that are part of a published offer. If a SKU is not part of a published offer, this field will only be returned if set for the inventory item. For implementation help, refer to eBay API documentation"
+ },
+ "conditionDescription": {
+ "type": "string",
+ "description": "This string field is used by the seller to more clearly describe the condition of used items, or items that are not 'Brand New', 'New with tags', or 'New in box'. The ConditionDescription field is available for all categories. If the ConditionDescription field is used with an item in a new condition (Condition IDs 1000-1499), eBay will simply ignore this field if included, and eBay will return a warning message to the user. This field should only be used to further clarify the condition of the used item. It should not be used for branding, promotions, shipping, returns, payment or other information unrelated to the condition of the item. Make sure that the condition value, condition description, listing description, and the item's pictures do not contradict one another.
Max length: 1000"
+ },
+ "conditionDescriptors": {
+ "type": "array",
+ "description": "This container is used by the seller to provide additional information about the condition of an item in a structured format. Condition descriptors are name-value attributes that can be either closed set or open text inputs.
For trading card and coin listings in applicable categories, sellers must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition to specify the item as Graded or Ungraded, respectively. Use of either of these conditions requires the seller to use this array to provide one or more applicable Condition Descriptor name-value pairs.
To retrieve all condition descriptor numeric IDs for a category, use the getItemConditionPolicies method of the Metadata API.",
+ "items": {
+ "$ref": "#/components/schemas/ConditionDescriptor"
+ }
+ },
+ "groupIds": {
+ "type": "array",
+ "description": "This array is returned if the inventory item is associated with any inventory item group(s). The value(s) returned in this array are the unique identifier(s) of the inventory item group(s). This array is not returned if the inventory item is not associated with any inventory item groups.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "inventoryItemGroupKeys": {
+ "type": "array",
+ "description": "This array is returned if the inventory item is associated with any inventory item group(s). The value(s) returned in this array are the unique identifier(s) of the inventory item's variation in a multiple-variation listing. This array is not returned if the inventory item is not associated with any inventory item groups.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "locale": {
+ "type": "string",
+ "description": "This field returns the natural language that was provided in the field values of the request payload (i.e., en_AU, en_GB or de_DE). For implementation help, refer to eBay API documentation"
+ },
+ "packageWeightAndSize": {
+ "description": "This container is used to specify the dimensions and weight of a shipping package.",
+ "$ref": "#/components/schemas/PackageWeightAndSize"
+ },
+ "product": {
+ "description": "This container is used in a createOrReplaceInventoryItem call to pass in a Global Trade Item Number (GTIN) or a Brand and Manufacturer Part Number (MPN) pair to identify a product to be matched with a product in the eBay catalog. If a match is found in the eBay product catalog, the inventory item is automatically populated with available product details such as a title, a subtitle, a product description, item specifics, and links to stock images for the product.",
+ "$ref": "#/components/schemas/Product"
+ },
+ "sku": {
+ "type": "string",
+ "description": "The seller-defined Stock-Keeping Unit (SKU) of the inventory item. The seller should have a unique SKU value for every product that they sell."
+ }
}
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "25001": {
- "domain": "API_INVENTORY",
- "category": "APPLICATION",
- "description": "System error. {additionalInfo}"
+ },
+ "InventoryItems": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "This is the URL to the current page of inventory items."
+ },
+ "inventoryItems": {
+ "type": "array",
+ "description": "This container is an array of one or more inventory items, with detailed information on each inventory item.",
+ "items": {
+ "$ref": "#/components/schemas/InventoryItemWithSkuLocaleGroupid"
+ }
+ },
+ "limit": {
+ "type": "integer",
+ "description": "This integer value is the number of inventory items that will be displayed on each results page.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "This is the URL to the next page of inventory items. This field will only be returned if there are additional inventory items to view."
+ },
+ "prev": {
+ "type": "string",
+ "description": "This is the URL to the previous page of inventory items. This field will only be returned if there are previous inventory items to view."
+ },
+ "size": {
+ "type": "integer",
+ "description": "This integer value indicates the total number of pages of results that are available. This number will depend on the total number of inventory items available for viewing, and on the limit value.",
+ "format": "int32"
+ },
+ "total": {
+ "type": "integer",
+ "description": "This integer value is the total number of inventory items that exist for the seller's account. Based on this number and on the limit value, the seller may have to toggle through multiple pages to view all inventory items.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used by the base response payload of getInventoryItems call. "
+ },
+ "InventoryLocation": {
+ "type": "object",
+ "properties": {
+ "location": {
+ "description": "This container is used to add any addition physical address and geographical coordinate information for a warehouse, store, or fulfillment center inventory location.
Note: For warehouse and store inventory locations, address fields can be updated any number of times. For fulfilment center locations, address fields cannot be updated. However, if any address fields were omitted during the createInventoryLocation call, they can be added through this method.
Note: When updating a warehouse location to a fulfillment center, sellers can update any of the address fields a single time during the same call used to make this update. After this, they can no longer be updated. ",
+ "$ref": "#/components/schemas/LocationDetails"
+ },
+ "locationAdditionalInformation": {
+ "type": "string",
+ "description": "This text field is used by the merchant to provide/update additional information about an inventory location. Whatever text is passed in this field will replace the current text string defined for this field. If the text will not change, the same text should be passed in once again.
Max length: 256"
+ },
+ "locationInstructions": {
+ "type": "string",
+ "description": "This text field is generally used by the merchant to provide/update special pickup instructions for a store inventory location. Although this field is optional, it is recommended that merchants provide this field to create a pleasant and easy pickup experience for In-Store Pickup and Click and Collect orders. If this field is not included in the call request payload, eBay will use the default pickup instructions contained in the merchant's profile (if available). Whatever text is passed in this field will replace the current text string defined for this field. If the text will not change, the same text should be passed in once again.
Max length: 1000"
+ },
+ "locationTypes": {
+ "type": "array",
+ "description": "This container is used to update the location type(s) associated with an inventory location.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "locationWebUrl": {
+ "type": "string",
+ "description": "This text field is used by the merchant to provide/update the Website address (URL) associated with the inventory location. The URL that is passed in this field will replace any other URL that may be defined for this field.
Max length: 512"
+ },
+ "name": {
+ "type": "string",
+ "description": "This text field is used by the merchant to update the name of the inventory location. This name should be a human-friendly name as it will be in In-Store Pickup and Click and Collect listings. A name is not required for warehouse locations. For store locations, this field is not immediately required, but will be required before an offer enabled with the In-Store Pickup or Click and Collect capability can be published. So, if the seller omitted this field in the createInventoryLocation call, it is required for an updateInventoryLocation call. The name that is passed in this field will replace any other name that may be defined for this field."
+ },
+ "operatingHours": {
+ "type": "array",
+ "description": "This container is used to provide/update the regular operating hours for a store location during the days of the week. A dayOfWeekEnum field and an intervals container will be needed for each day of the week that the location is open. Note that if operating hours are already set for a location for a specific day of the week, whatever is set through an updateInventoryLocation call will override those existing hours.",
+ "items": {
+ "$ref": "#/components/schemas/OperatingHours"
+ }
+ },
+ "phone": {
+ "type": "string",
+ "description": "This text field is used by the merchant to provide/update the phone number for the inventory location. The phone number that is passed in this field will replace any other phone number that may be defined for this field.
Max length: 36"
+ },
+ "specialHours": {
+ "type": "array",
+ "description": "This container is used to provide/update the special operating hours for a store location on a specific date, such as a holiday. The special hours specified for the specific date will override the normal operating hours for that particular day of the week. If special hours have already been set up for an inventory location, specifying special hours through an updateInventoryLocation call will only add to the list, unless the date(s) used are the same special date(s) already set up, in which case, the special hours set up through the updateInventoryLocation call will override the existing special hours.",
+ "items": {
+ "$ref": "#/components/schemas/SpecialHours"
+ }
+ },
+ "timeZoneId": {
+ "type": "string",
+ "description": "This field is used to provide/update the time zone of the inventory location being created. This value should be in Olson format (for example America/Vancouver). For supported values, see Java Supported Zone Ids and Offsets.
Note: If specified, this time zone will be used for all hour related fields. If this field is not specified, the time zone will be calculated from the provided address fields."
+ },
+ "fulfillmentCenterSpecifications": {
+ "description": "This container is used to update information about a fulfillment center's shipping specifications, such as the weekly cut-off time schedule for order handling and any cut-off overrides.",
+ "$ref": "#/components/schemas/FulfillmentCenterSpecifications"
+ }
+ },
+ "description": "This type is used by the updateInventoryLocation call to update operating hours, special hours, phone number, and other minor details of an inventory location."
+ },
+ "InventoryLocationFull": {
+ "type": "object",
+ "properties": {
+ "location": {
+ "description": "This required container is used to set the physical address and geographical coordinates of a warehouse, store, or fulfillment center inventory location. A warehouse location only requires the postal code and country OR city, province/state, and country, and does not require a full street address. However, the seller may still supply a full street address for a warehouse location. A complete address (addressLine1, city, stateOrProvince, postalCode, and country) is required for store and fulfillment center locations.
Note: For fulfillment center locations, the addressLine1, stateOrProvince, country and postalCode fields cannot be changed once they have been set, though they can be added through the updateInventoryLocation method if they were omitted during location creation.",
+ "$ref": "#/components/schemas/LocationDetails"
+ },
+ "locationAdditionalInformation": {
+ "type": "string",
+ "description": "This text field is used by the merchant to provide additional information about an inventory location.
Max length: 256"
+ },
+ "locationInstructions": {
+ "type": "string",
+ "description": "This text field is generally used by the merchant to provide special pickup instructions for a store inventory location. Although this field is optional, it is recommended that merchants provide this field to create a pleasant and easy pickup experience for In-Store Pickup and Click and Collect orders. If this field is not included in the call request payload, eBay will use the default pickup instructions contained in the merchant's profile (if available)."
+ },
+ "locationTypes": {
+ "type": "array",
+ "description": "This container is used to define the function of the inventory location. Typically, an inventory location will serve as a store, warehouse, or fulfillment center, but in some cases, an inventory location may be more than one type.
For In-Store Pickup inventory, set StoreTypeEnum to STORE.
To utilize the Multi-warehouse program, set StoreTypeEnum to FULFILLMENT_CENTER.
If this container is omitted, the location type of the inventory location will default to WAREHOUSE. See StoreTypeEnum for the supported values.
Default: WAREHOUSE",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "locationWebUrl": {
+ "type": "string",
+ "description": "This text field is used by the merchant to provide the Website address (URL) associated with the inventory location.
Max length: 512"
+ },
+ "merchantLocationStatus": {
+ "type": "string",
+ "description": "This field is used to indicate whether the inventory location will be enabled (inventory can be loaded to location) or disabled (inventory can not be loaded to location). If this field is omitted, a successful createInventoryLocation call will automatically enable the location. A merchant may want to create a new location but leave it as disabled if the location is not yet ready for active inventory. Once the location is ready, the merchant can use the enableInventoryLocation call to enable a location that is in a disabled state.
See StatusEnum for the supported values.
Default: ENABLED For implementation help, refer to eBay API documentation"
+ },
+ "name": {
+ "type": "string",
+ "description": "The seller-defined name of the inventory location. This name should be a human-friendly name as it will be displayed in In-Store Pickup and Click and Collect listings. A name is not required for warehouse locations. For store locations, this field is not immediately required, but will be required before an offer enabled with the In-Store Pickup or Click and Collect capability can be published. So, if the seller omits this field in a createInventoryLocation call, it becomes required for an updateInventoryLocation call.
Max length: 1000"
+ },
+ "operatingHours": {
+ "type": "array",
+ "description": "This container is used to express the regular operating hours for a store location during each day of the week. A dayOfWeekEnum field and an intervals container will be needed for each day of the week that the store location is open.
Although not technically required, this container is highly recommended to be used to specify operating hours for a store location.",
+ "items": {
+ "$ref": "#/components/schemas/OperatingHours"
+ }
+ },
+ "phone": {
+ "type": "string",
+ "description": "This field is used to specify the phone number for an inventory location.
Max length: 36"
+ },
+ "specialHours": {
+ "type": "array",
+ "description": "This container is used to express the special operating hours for a store inventory location on a specific date, such as a holiday. The special hours specified for the specific date will override the normal operating hours for that particular day of the week.",
+ "items": {
+ "$ref": "#/components/schemas/SpecialHours"
+ }
+ },
+ "timeZoneId": {
+ "type": "string",
+ "description": "This field specifies the time zone of the inventory location being created. This value should be in Olson format (for example America/Vancouver). For supported values, see Java Supported Zone Ids and Offsets.
Note: If specified, this time zone will be used for all hour related fields. If this field is not specified for a fulfillment center location, the time zone will be calculated from the provided address fields."
+ },
+ "fulfillmentCenterSpecifications": {
+ "description": "This container is used to specify information about a fulfillment center's shipping specifications, such as the weekly cut-off time schedule for order handling and any cut-off time overrides.
Note: This container is required if one of the locationTypes of the inventory location is FULFILLMENT_CENTER, and is not applicable to other location types.",
+ "$ref": "#/components/schemas/FulfillmentCenterSpecifications"
+ }
+ },
+ "description": "This type is used by the createInventoryLocation call to provide details on the inventory location, including the location's name, physical address, operating hours, special hours, phone number and other details of an inventory location."
+ },
+ "InventoryLocationResponse": {
+ "type": "object",
+ "properties": {
+ "location": {
+ "description": "This container provides location details of an inventory location. The address container will always be returned, but it will not always have a complete street address. Except in the case of a store or fulfillment center location, a full address is not a requirement when setting up an inventory location. The geoCoordinates container will only be returned if the merchant provided geographical coordinates. The locationId field is always returned, but this value is only used internally by eBay.",
+ "$ref": "#/components/schemas/Location"
+ },
+ "locationAdditionalInformation": {
+ "type": "string",
+ "description": "This text field provides additional information about an inventory location. This field is returned if it is set for the location."
+ },
+ "locationInstructions": {
+ "type": "string",
+ "description": "This text field is used by the merchant to provide special pickup instructions for the store location. This field can help create a pleasant and easy pickup experience for In-Store Pickup and Click and Collect orders. If this field was not set up through a createInventoryLocation or a updateInventoryLocation call, eBay will use the default pickup instructions contained in the merchant's profile."
+ },
+ "locationTypes": {
+ "type": "array",
+ "description": "This container defines the function of the inventory location. Typically, a location will serve as a store, warehouse, or fulfillment center, but in some cases, an inventory location may be more than one type.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "locationWebUrl": {
+ "type": "string",
+ "description": "This text field shows the Website address (URL) associated with the inventory location. This field is returned if defined for the location."
+ },
+ "merchantLocationKey": {
+ "type": "string",
+ "description": "The unique identifier of the inventory location. This identifier is set up by the merchant when the location is first created with the createInventoryLocation call."
+ },
+ "merchantLocationStatus": {
+ "type": "string",
+ "description": "This field indicates whether the inventory location is enabled (inventory can be loaded to location) or disabled (inventory can not be loaded to location). The merchant can use the enableInventoryLocation call to enable a location in disabled status, or the disableInventoryLocation call to disable a location in enabled status. For implementation help, refer to eBay API documentation"
+ },
+ "name": {
+ "type": "string",
+ "description": "The name of the inventory location. This name should be a human-friendly name as it will be displayed in In-Store Pickup and Click and Collect listings. For store inventory locations, this field is not required for the createInventoryLocation call, but a store inventory location must have a defined name value before an In-Store Pickup and Click and Collect enabled offer is published. So, if the seller omits this field in the createInventoryLocation call, it will have to be added later through a updateInventoryLocation call."
+ },
+ "operatingHours": {
+ "type": "array",
+ "description": "This container shows the regular operating hours for a store location during the days of the week. A dayOfWeekEnum field and an intervals container is shown for each day of the week that the location is open.",
+ "items": {
+ "$ref": "#/components/schemas/OperatingHours"
+ }
+ },
+ "phone": {
+ "type": "string",
+ "description": "The phone number for an inventory location. This field will typically only be returned for store locations."
+ },
+ "specialHours": {
+ "type": "array",
+ "description": "This container shows the special operating hours for a store or fulfillment center location on a specific date or dates.",
+ "items": {
+ "$ref": "#/components/schemas/SpecialHours"
+ }
+ },
+ "timeZoneId": {
+ "type": "string",
+ "description": "This field specifies the time zone of the inventory location being created. This value should be in Olson format (for example America/Vancouver). For supported values, see Java Supported Zone Ids and Offsets."
+ },
+ "fulfillmentCenterSpecifications": {
+ "description": "This container provides information about a fulfillment center's shipping specifications, such as the weekly cut-off time schedule for order handling and any cut-off time overrides.
Note: This field is only returned for fulfillment center locations.",
+ "$ref": "#/components/schemas/FulfillmentCenterSpecifications"
+ }
+ },
+ "description": "This type is used by the base response of the getInventoryLocation and getInventoryLocations calls. These responses provide details about inventory location(s) defined for the merchant's account."
+ },
+ "ListingDetails": {
+ "type": "object",
+ "properties": {
+ "listingId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay listing that is associated with the published offer. "
+ },
+ "listingOnHold": {
+ "type": "boolean",
+ "description": "Indicates if a listing is on hold due to an eBay policy violation.
If a listing is put on hold, users are unable to view the listing details, the listing is hidden from search, and all attempted purchases, offers, and bids for the listing are blocked. eBay, however, gives sellers the opportunity to address violations and get listings fully reinstated. A listing will be ended if a seller does not address a violation, or if the violation can not be rectified.
If a listing is fixable, the seller should be able to view the listing details and this boolean will be returned as true.
Once a listing is fixed, this boolean will no longer be returned.
"
+ },
+ "listingStatus": {
+ "type": "string",
+ "description": "The enumeration value returned in this field indicates the status of the listing that is associated with the published offer. For implementation help, refer to eBay API documentation"
+ },
+ "soldQuantity": {
+ "type": "integer",
+ "description": "This integer value indicates the quantity of the product that has been sold for the published offer.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used by the listing container in the getOffer and getOffers calls to provide the eBay listing ID, the listing status, and quantity sold for the offer. The listing container is only returned for published offers, and is not returned for unpublished offers."
+ },
+ "ListingPolicies": {
+ "type": "object",
+ "properties": {
+ "bestOfferTerms": {
+ "description": "This container is used if the seller would like to support the Best Offer feature on their listing. To enable the Best Offer feature, the seller will have to set the bestOfferEnabled field to true, and the seller also has the option of setting 'auto-accept' and 'auto-decline' price thresholds.
Note: Best Offer is unavailable for multi-variation listings.
This container is only returned if Best Offer is enabled on listing.",
+ "$ref": "#/components/schemas/BestOffer"
+ },
+ "eBayPlusIfEligible": {
+ "type": "boolean",
+ "description": "This field is included in an offer and set to true if a Top-Rated seller is opted in to the eBay Plus program. With the eBay Plus program, qualified sellers must commit to next-day delivery of the item, and the buyers must have an eBay Plus subscription to be eligible to receive the benefits of this program, which are free, next-day delivery, as well as free returns.
Note: Currently, this program is only available on the Germany and Australian sites.
This field will be returned in the getOffer and getOffers methods if set for the offer."
+ },
+ "fulfillmentPolicyId": {
+ "type": "string",
+ "description": "This unique identifier indicates the fulfillment business policy that will be used once an offer is published and converted to an eBay listing. This fulfillment business policy will set all fulfillment-related settings for the eBay listing.
Business policies are not immediately required for offers, but are required before an offer can be published. The seller should review the fulfillment business policy before assigning it to the offer to make sure it is compatible with the inventory item and the offer settings. The seller may also want to review the shipping service costs in the fulfillment policy, and that seller might decide to override the shipping costs for one or more shipping service options by using the shippingCostOverrides container.
Business policies can be created and managed in My eBay or with the Account API. To get a list of all return policies associated with a seller's account on a specific eBay Marketplace, use the Account API's getFulfillmentPolicies method. There are also calls in the Account API to retrieve a fulfillment policy by policy ID or policy name.
This field will be returned in the getOffer and getOffers methods if set for the offer.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Business policies are not immediately required for offers, but are required before an offer can be published. The seller should review the payment business policy to make sure that it is compatible with the marketplace and listing category before assigning it to the offer.
Business policies can be created and managed in My eBay or with the Account API. To get a list of all payment policies associated with a seller's account on a specific eBay Marketplace, use the Account API's getPaymentPolicies method. There are also calls in the Account API to retrieve a payment policy by policy ID or policy name.
This field will be returned in the getOffer and getOffers methods if set for the offer.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Product compliance policies provide buyers with important information and disclosures about products. For example, if you sell batteries and specific disclosures are required to be shared with all potential buyers, your global product compliance policy could contain the required disclosures.
A maximum of six (6) global product compliance policies may apply to each offer.Note: For countries that support country-specific policies, use regionalProductCompliancePolicies to apply them to an offer.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "regionalProductCompliancePolicies": {
+ "description": "A comma-delimited list of unique identifiers indicating the seller-created country-specific product compliance policies that that will be used once an offer is published and converted to a listing.
Product compliance policies provide buyers with important information and disclosures about products. For example, if you sell batteries in a country requiring disclosures that apply only to that country, a country-specific product compliance policy could contain this information.
Each offer may include up to six (6) product compliance policies for each of the following countries:- United Kingdom [GB]
- Germany [DE]
- France [FR]
- Italy [IT]
- Spain [ES]
For example, if a seller offers products in the UK, Germany, and Italy, each of which requires custom product compliance information, up to 18 policies (i.e., 6 policies x 3 countries,) may be included with each offer.Note: Product compliance policies that apply to all countries to which a seller ships are specified using productCompliancePolicyIds.",
+ "$ref": "#/components/schemas/RegionalProductCompliancePolicies"
+ },
+ "regionalTakeBackPolicies": {
+ "description": "The list of unique identifiers indicating the seller-created country-specific take-back policies that will be used once an offer is published and converted to a listing. The law in some countries may require sellers to take back a used product when the buyer buys a new product.
Each offer may include one (1) country-specific take-back policy for each of the following countries:- United Kingdom [GB]
- Germany [DE]
- France [FR]
- Italy [IT]
- Spain [ES]
Note: Take-back policies that apply to all countries to which a seller ships are specified using takeBackPolicyId.",
+ "$ref": "#/components/schemas/RegionalTakeBackPolicies"
+ },
+ "returnPolicyId": {
+ "type": "string",
+ "description": "This unique identifier indicates the return business policy that will be used once an offer is published and converted to an eBay listing. This return business policy will set all return policy settings for the eBay listing.
Note: As a part of Digital Services Act (DSA) requirements, as of April 3, 2023, buyers in the EU must be allowed to return an item within 14 days or more, unless the item is exempt. Where applicable, sellers should update their return policies to reflect this requirement of accepting returns from EU buyers.
Business policies are not immediately required for offers, but are required before an offer can be published. The seller should review the return business policy before assigning it to the offer to make sure it is compatible with the inventory item and the offer settings.
Business policies can be created and managed in My eBay or with the Account API. To get a list of all return policies associated with a seller's account on a specific eBay Marketplace, use the Account API's getReturnPolicies call. There are also calls in the Account API to retrieve a return policy by policy ID or policy name.
This field will be returned in the getOffer and getOffers methods if set for the offer.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
DOMESTIC to override a domestic shipping service option, or to INTERNATIONAL to override an international shipping service option.
A separate ShippingCostOverrides node is needed for each shipping service option whose costs are being overridden. All defined fields of the shippingCostOverrides container should be included, even if the shipping costs and surcharge values are not changing.
The shippingCostOverrides container is returned in the getOffer and getOffers calls if one or more shipping cost overrides are being applied to the fulfillment policy.",
+ "items": {
+ "$ref": "#/components/schemas/ShippingCostOverride"
+ }
+ },
+ "takeBackPolicyId": {
+ "type": "string",
+ "description": "This unique identifier indicates the seller-created global take-back policy that will be used once an offer is published and converted to a listing.
One (1) global take-back policy may be specified per offer.
Note: For countries that support country-specific policies, use regionalTakeBackPolicies to apply them to an offer."
+ }
+ },
+ "description": "This type is used to identify business policies including payment, return, and fulfillment policies, as well as to identify custom policies. These policies are, or will be, associated with the listing. Every published offer must have a payment, return, and fulfillment business policy associated with it. Additionally, depending on the country/countries in which sellers are offering products and/or services to consumers (e.g., residents of the European Union,) specifying additional polices may be required.
This type is also used to override the shipping costs of one or more shipping service options that are associated with the fulfillment policy, to enable eBay Plus eligibility for a listing, or to enable the Best Offer feature on the listing."
+ },
+ "Location": {
+ "type": "object",
+ "properties": {
+ "address": {
+ "description": "The address container is always returned in getInventoryLocation/getInventoryLocations calls. Except in the case of a store or fulfillment center location, a full address is not a requirement when setting up an inventory location.",
+ "$ref": "#/components/schemas/Address"
+ },
+ "geoCoordinates": {
+ "description": "This container displays the Global Positioning System (GPS) latitude and longitude coordinates for the inventory location.
This container is only returned if the geo-coordinates are set for an inventory location.",
+ "$ref": "#/components/schemas/GeoCoordinates"
+ },
+ "locationId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for the location.
Note: This field should not be confused with the seller-defined merchantLocationKey value. It is the merchantLocationKey value which is used to identify an inventory location when working with inventory location API calls. The locationId value is only used internally by eBay."
+ }
+ },
+ "description": "A complex type that is used to provide the physical address of a location, and it geo-coordinates."
+ },
+ "LocationAvailabilityDetails": {
+ "type": "object",
+ "properties": {
+ "merchantLocationKey": {
+ "type": "string",
+ "description": "The unique identifier of a sellerās fulfillment center location where inventory is available for the item or item variation.
Note: When creating a location mapping using the createOrReplaceSkuLocationMapping method, the value entered in this field must be associated with a location with the FULFILLMENT_CENTER location type, or an error will occur. Sellers can check the locationTypes array in the response of the getInventoryLocations method to see if their location has a value of FULFILLMENT_CENTER."
+ }
+ },
+ "description": "This type provides the unique identifier of an inventory location that is associated with a SKU within a listing."
+ },
+ "LocationDetails": {
+ "type": "object",
+ "properties": {
+ "address": {
+ "description": "This required container sets the physical address of an inventory location. Except in the case store or fulfillment center location, a full address is not a requirement when setting up a location. For warehouse locations, the fields required in this container are either of the following sets:- city, stateOrProvince, and country
- postalCode and country
",
+ "$ref": "#/components/schemas/Address"
+ },
+ "geoCoordinates": {
+ "description": "This container is used to set the Global Positioning System (GPS) latitude and longitude coordinates for the inventory location.
Geographical coordinates are required for the location of In-Store Pickup inventory. ",
+ "$ref": "#/components/schemas/GeoCoordinates"
+ }
+ },
+ "description": "This type is used by the createInventoryLocation call to provide an full or partial address of an inventory location."
+ },
+ "LocationMapping": {
+ "type": "object",
+ "properties": {
+ "locations": {
+ "type": "array",
+ "description": "This array represents a collection of fulfillment center locations mapped to a SKU.
Note: Only the first 50 locations mapped to a SKU will be considered when calculating estimated delivery dates. Sellers can set up more than 50 locations using this method, but only the first 50 locations will be considered for calculating the estimates.",
+ "items": {
+ "$ref": "#/components/schemas/LocationAvailabilityDetails"
+ }
+ }
+ },
+ "description": "This type provides an array of locations that are associated with a SKU within a listing."
+ },
+ "LocationResponse": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the current page of results from the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The number of items returned on a single page from the result set.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value is set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
+ "format": "int32"
+ },
+ "locations": {
+ "type": "array",
+ "description": "An array of one or more of the merchant's inventory locations.",
+ "items": {
+ "$ref": "#/components/schemas/InventoryLocationResponse"
+ }
+ }
+ },
+ "description": "This type is used by the base response payload for the getInventoryLocations call."
+ },
+ "Manufacturer": {
+ "type": "object",
+ "properties": {
+ "addressLine1": {
+ "type": "string",
+ "description": "The first line of the product manufacturer's street address.
Max length: 180 characters"
+ },
+ "addressLine2": {
+ "type": "string",
+ "description": "The second line of the product manufacturer's street address. This field is not always used, but can be used for secondary address information such as 'Suite Number' or 'Apt Number'.
Max length: 180 characters"
+ },
+ "city": {
+ "type": "string",
+ "description": "The city of the product manufacturer's street address.
Max length: 64 characters"
+ },
+ "companyName": {
+ "type": "string",
+ "description": "The company name of the product manufacturer.
Max length: 100 characters"
+ },
+ "contactUrl": {
+ "type": "string",
+ "description": "The contact URL of the product manufacturer.
Max length: 250 characters"
+ },
+ "country": {
+ "type": "string",
+ "description": "This defines the list of valid country codes, adapted from http://www.iso.org/iso/country_codes, ISO 3166-1 country code. List elements take the following form to identify a two-letter code with a short name in English, a three-digit code, and a three-letter code: For example, the entry for Japan includes Japan, 392, JPN. Short codes provide uniform recognition, avoiding language-dependent country names. The number code is helpful where Latin script may be problematic. Not all listed codes are universally recognized as countries, for example: code AQ is Antarctica, 010, ATA For implementation help, refer to eBay API documentation"
+ },
+ "email": {
+ "type": "string",
+ "description": "The product manufacturer's business email address.
Max length: 180 characters"
+ },
+ "phone": {
+ "type": "string",
+ "description": "The product manufacturer's business phone number.
Max length: 64 characters"
+ },
+ "postalCode": {
+ "type": "string",
+ "description": "The postal code of the product manufacturer's street address.
Max length: 9 characters"
+ },
+ "stateOrProvince": {
+ "type": "string",
+ "description": "The state or province of the product manufacturer's street address.
Max length: 64 characters"
+ }
+ },
+ "description": "This type provides name and contact information about the manufacturer of the item."
+ },
+ "MigrateListing": {
+ "type": "object",
+ "properties": {
+ "listingId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay listing to migrate to the new Inventory model. In the Trading API, this field is known as the ItemID.
Up to five unique eBay listings may be specified here in separate listingId fields. The seller should make sure that each of these listings meet the requirements that are stated at the top of this Call Reference page."
+ }
+ },
+ "description": "This type is used to specify one to five eBay listings that will be migrated to the new Inventory model."
+ },
+ "MigrateListingResponse": {
+ "type": "object",
+ "properties": {
+ "errors": {
+ "type": "array",
+ "description": "If one or more errors occur with the attempt to migrate the listing, this container will be returned with detailed information on each error.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "inventoryItemGroupKey": {
+ "type": "string",
+ "description": "This field will only be returned for a multiple-variation listing that the seller attempted to migrate. Its value is auto-generated by eBay. For a multiple-variation listing that is successfully migrated to the new Inventory model, eBay automatically creates an inventory item group object for the listing, and the seller will be able to retrieve and manage that new inventory item group object by using the value in this field."
+ },
+ "inventoryItems": {
+ "type": "array",
+ "description": "This container exists of an array of SKU values and offer IDs. For single-variation listings, this will only be one SKU value and one offer ID (if listing was successfully migrated), but multiple SKU values and offer IDs will be returned for multiple-variation listings.",
+ "items": {
+ "$ref": "#/components/schemas/InventoryItemListing"
+ }
+ },
+ "listingId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay listing that the seller attempted to migrate."
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "This is the unique identifier of the eBay Marketplace where the listing resides. The value fo the eBay US site will be EBAY_US. For implementation help, refer to eBay API documentation"
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "This field is returned for each listing that the seller attempted to migrate. See the HTTP status codes table to see which each status code indicates.",
+ "format": "int32"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "If one or more warnings occur with the attempt to migrate the listing, this container will be returned with detailed information on each warning. It is possible that a listing can be successfully migrated even if a warning occurs.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type is used to display the results of each listing that the seller attempted to migrate."
+ },
+ "NameValueList": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "This string value identifies the motor vehicle aspect, such as 'make', 'model', 'year', 'trim', and 'engine'. Typically, the make, model, and year of the motor vehicle are always required, with the trim and engine being necessary sometimes, but it will be dependent on the part or accessory, and on the vehicle class.
The getCompatibilityProperties method of the Taxonomy API can be used to retrieve applicable vehicle aspect names for a specified category."
+ },
+ "value": {
+ "type": "string",
+ "description": "This string value identifies the motor vehicle aspect specified in the corresponding name field. For example, if the name field is 'make', this field may be 'Toyota', or if the name field is 'model', this field may be 'Camry'.
The getCompatibilityPropertyValues method of the Taxonomy API can be used to retrieve possible values for vehicle aspect names."
+ }
+ },
+ "description": "This type is used by the compatibilityProperties container to identify a motor vehicle using name/value pairs."
+ },
+ "OfferKeyWithId": {
+ "type": "object",
+ "properties": {
+ "offerId": {
+ "type": "string",
+ "description": "The unique identifier of an unpublished offer for which expected listing fees will be retrieved. One to 250 offerId values can be passed in to the offers container for one getListingFees call.
Use the getOffers method to retrieve offer IDs.
Note: Errors will occur if offerId values representing published offers are passed in."
+ }
+ },
+ "description": "This type is used by the getListingFees call to indicate the unpublished offer(s) for which expected listing fees will be retrieved. The user passes in one or more offerId values (a maximum of 250). See the Standard selling fees help page for more information on listing fees."
+ },
+ "OfferKeysWithId": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "This container is used to identify one or more (up to 250) unpublished offers for which expected listing fees will be retrieved. The user passes one or more offerId values (maximum of 250) in to this container to identify the unpublished offers in which to retrieve expected listing fees. This call is only applicable for offers in the unpublished state.
The call response gives aggregate fee amounts per eBay marketplace, and does not give fee information at the individual offer level.",
+ "items": {
+ "$ref": "#/components/schemas/OfferKeyWithId"
+ }
+ }
+ },
+ "description": "This type is used by the base request payload of the getListingFees call."
+ },
+ "OfferPriceQuantity": {
+ "type": "object",
+ "properties": {
+ "availableQuantity": {
+ "type": "integer",
+ "description": "This field is used if the seller wants to modify the current quantity of the inventory item that will be available for purchase in the offer (identified by the corresponding offerId value).
This value represents the quantity of the item that is available in the marketplace specified within the offer, not the total quantity available. Because of this, this value should not exceed the value specified in the quantity field of the shipToLocationAvailability container (the total available quantity of the item across all marketplaces).
Note: To ensure that the available quantity allocated to a specific marketplace doesn't exceed the total available stock, the quantity specified on a listing will be the minimum value between this field and the quantity field.
Either the availableQuantity field or the price container is required, but not necessarily both.",
+ "format": "int32"
+ },
+ "offerId": {
+ "type": "string",
+ "description": "This field is the unique identifier of the offer. If an offers container is used to update one or more offers associated to a specific inventory item, the offerId value is required in order to identify the offer to update with a modified price and/or quantity.
The seller can use the getOffers method (passing in the correct SKU value as a query parameter) to retrieve offerId values for offers associated with the SKU."
+ },
+ "price": {
+ "description": "This container is used if the seller wants to modify the current price of the inventory item. The dollar value set here will be the new price of the inventory item in the offer (identified by the corresponding offerId value). Either the availableQuantity field or the price container is required, but not necessarily both.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type is used by the offers container in a Bulk Update Price and Quantity call to update the current price and/or quantity of one or more offers associated with a specific inventory item."
+ },
+ "OfferResponse": {
+ "type": "object",
+ "properties": {
+ "offerId": {
+ "type": "string",
+ "description": "The unique identifier of the offer that was just created with a createOffer call. It is not returned if the createOffer call fails to create an offer. This identifier will be needed for many offer-related calls. Note: The offerId value is only returned with a successful createOffer call. This field will not be returned in the updateOffer response.
"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "This container will contain an array of errors and/or warnings when a call is made, and errors and/or warnings occur.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type is used by the response payload of the createOffer and updateOffer calls. The offerId field contains the unique identifier for the offer if the offer is successfully created by the createOffer call. The warnings field contains any errors and/or warnings that may have been triggered by the call. Note: The offerId value is only returned with a successful createOffer call. This field will not be returned in the updateOffer response.
"
+ },
+ "OfferResponseWithListingId": {
+ "type": "object",
+ "properties": {
+ "errors": {
+ "type": "array",
+ "description": "This container will be returned if there were one or more errors associated with publishing the offer.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "listingId": {
+ "type": "string",
+ "description": "The unique identifier of the newly-created eBay listing. This field is only returned if the seller successfully published the offer and created the new eBay listing."
+ },
+ "offerId": {
+ "type": "string",
+ "description": "The unique identifier of the offer that the seller published (or attempted to publish)."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "The HTTP status code returned in this field indicates the success or failure of publishing the offer specified in the offerId field. See the HTTP status codes table to see which each status code indicates.",
+ "format": "int32"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "This container will be returned if there were one or more warnings associated with publishing the offer.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type is used to indicate the status of each offer that the user attempted to publish. If an offer is successfully published, an eBay listing ID (also known as an Item ID) is returned. If there is an issue publishing the offer and creating the new eBay listing, the information about why the listing failed should be returned in the errors and/or warnings containers."
+ },
+ "OfferSkuResponse": {
+ "type": "object",
+ "properties": {
+ "errors": {
+ "type": "array",
+ "description": "This container will be returned at the offer level, and will contain one or more errors if any occurred with the attempted creation of the corresponding offer.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "format": {
+ "type": "string",
+ "description": "This enumeration value indicates the listing format of the offer. For implementation help, refer to eBay API documentation"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "This enumeration value is the unique identifier of the eBay marketplace for which the offer will be made available. This enumeration value should be the same for all offers since the bulkCreateOffer method can only be used to create offers for one eBay marketplace at a time. For implementation help, refer to eBay API documentation"
+ },
+ "offerId": {
+ "type": "string",
+ "description": "The unique identifier of the newly-created offer. This identifier should be automatically created by eBay if the creation of the offer was successful. It is not returned if the creation of the offer was not successful. In which case, the user may want to scan the corresponding errors and/or warnings container to see what the issue may be."
+ },
+ "sku": {
+ "type": "string",
+ "description": "The seller-defined Stock-Keeping Unit (SKU) of the inventory item. The sku value is required for each product offer that the seller is trying to create, and it is always returned to identified the product that is associated with the offer."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "The integer value returned in this field is the http status code. If an offer is created successfully, the value returned in this field should be 200. A user can view the HTTP status codes section for information on other status codes that may be returned with the bulkCreateOffer method.",
+ "format": "int32"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "This container will be returned at the offer level, and will contain one or more warnings if any occurred with the attempted creation of the corresponding offer. Note that it is possible that an offer can be created successfully even if one or more warnings are triggered.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type is used by the bulkCreateOffer response to show the status of each offer that the seller attempted to create with the bulkCreateOffer method. For each offer that is created successfully, the returned statusCode value should be 200, and a unique offerId should be created for each offer. If any issues occur with the creation of any offers, errors and/or warnings containers will be returned."
+ },
+ "Offers": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "This is the URL to the current page of offers."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "This integer value is the number of offers that will be displayed on each results page.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "This is the URL to the next page of offers. This field will only be returned if there are additional offers to view."
+ },
+ "offers": {
+ "type": "array",
+ "description": "This container is an array of one or more of the seller's offers for the SKU value that is passed in through the required sku query parameter.
Note: Currently, the Inventory API does not support the same SKU across multiple eBay marketplaces.
Max Occurs: 25",
+ "items": {
+ "$ref": "#/components/schemas/EbayOfferDetailsWithAll"
+ }
+ },
+ "prev": {
+ "type": "string",
+ "description": "This is the URL to the previous page of offers. This field will only be returned if there are previous offers to view."
+ },
+ "size": {
+ "type": "integer",
+ "description": "This integer value indicates the number of offers being displayed on the current page of results. This number will generally be the same as the limit value if there are additional pages of results to view.
Note: The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, getOffers will return two offers and this value will be 2. Otherwise, only one offer will be returned and this value will be 1.",
+ "format": "int32"
+ },
+ "total": {
+ "type": "integer",
+ "description": "This integer value is the total number of offers that exist for the specified SKU value. Based on this number and on the limit value, the seller may have to toggle through multiple pages to view all offers.
Note: The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, getOffers will return two offers, so this value would be 2. Otherwise, only one offer will be returned and this value will be 1.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used by the base response of the getOffers call, and it is an array of one or more of the seller's offers, along with pagination data."
+ },
+ "OperatingHours": {
+ "type": "object",
+ "properties": {
+ "dayOfWeekEnum": {
+ "type": "string",
+ "description": "A dayOfWeekEnum value is required for each day of the week that the store location has regular operating hours.
This field is returned if operating hours are defined for the store location. For implementation help, refer to eBay API documentation"
+ },
+ "intervals": {
+ "type": "array",
+ "description": "This container is used to define the opening and closing times of a store location's working day (defined in the dayOfWeekEnum field). An intervals container is needed for each day of the week that the store location is open. If a store location closes for lunch (or any other period during the day) and then reopens, multiple open and close pairs are needed
This container is returned if operating hours are defined for the store location.",
+ "items": {
+ "$ref": "#/components/schemas/Interval"
+ }
+ }
+ },
+ "description": "This type is used to express the regular operating hours of a merchant's store or fulfillment center during the days of the week."
+ },
+ "Overrides": {
+ "type": "object",
+ "properties": {
+ "cutOffTime": {
+ "type": "string",
+ "description": "This field is used to override the cut-off time(s) specified in the weeklySchedule container. If an order is placed after this time in the specified date or date range, it will be handled by the seller on the following day.
Format: 00:00"
+ },
+ "endDate": {
+ "type": "string",
+ "description": "The end date of the cut-off time override in ISO 8601 format, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Note: If the cut-off time override is only for a single day, input the same date in the startDate and endDate fields.
Format: [YYYY]-[MM]-[DD]
Example: 2024-08-06
Note: The time zone for this date is specified from the timeZoneId field. If this field is not used, the time zone will be derived from the provided address."
+ },
+ "startDate": {
+ "type": "string",
+ "description": "The start date of the cut-off time override in ISO 8601 format, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Note: If the cut-off time override is only for a single day, input the same date in the startDate and endDate fields.
Format: [YYYY]-[MM]-[DD]
Example: 2024-08-04
Note: The time zone for this date is specified from the timeZoneId field. If this field is not used, the time zone will be derived from the provided address."
+ }
+ },
+ "description": "This type defines the override dates for cut-off times. This allows sellers to set special hours for their inventory location and specify different cut-off times on these days."
+ },
+ "PackageWeightAndSize": {
+ "type": "object",
+ "properties": {
+ "dimensions": {
+ "description": "This container is used to indicate the length, width, and height of the shipping package that will be used to ship the inventory item. The dimensions of a shipping package are needed when calculated shipping is used.
This container will be returned if package dimensions are set for the inventory item.",
+ "$ref": "#/components/schemas/Dimension"
+ },
+ "packageType": {
+ "type": "string",
+ "description": "This enumeration value indicates the type of shipping package used to ship the inventory item. The supported values for this field can be found in the PackageTypeEnum type.
This field will be returned if the package type is set for the inventory item.
Note: You can use the GeteBayDetails Trading API call to retrieve a list of supported package types for a specific marketplace. For implementation help, refer to eBay API documentation"
+ },
+ "shippingIrregular": {
+ "type": "boolean",
+ "description": "A value of true indicates that the package is irregular and cannot go through the stamping machine at the shipping service office. This field applies to calculated shipping only. Irregular packages require special or fragile handling."
+ },
+ "weight": {
+ "description": "This container is used to specify the weight of the shipping package that will be used to ship the inventory item. The weight of a shipping package are needed when calculated shipping is used, or if flat-rate shipping rates are used, but with a weight surcharge.
This field will be returned if package weight is set for the inventory item.",
+ "$ref": "#/components/schemas/Weight"
+ }
+ },
+ "description": "This type is used to indicate the package type, weight, and dimensions of the shipping package. Package weight and dimensions are required when calculated shipping rates are used, and weight alone is required when flat-rate shipping is used, but with a weight surcharge. See the Calculated shipping help page for more information on calculated shipping."
+ },
+ "PickupAtLocationAvailability": {
+ "type": "object",
+ "properties": {
+ "availabilityType": {
+ "type": "string",
+ "description": "The enumeration value in this field indicates the availability status of the inventory item at the merchant's physical store specified by the pickupAtLocationAvailability.merchantLocationKey field. This field is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.
See AvailabilityTypeEnum for more information about how/when you use each enumeration value. For implementation help, refer to eBay API documentation"
+ },
+ "fulfillmentTime": {
+ "description": "This container is used to indicate how soon an In-Store Pickup order will be available for pickup by the buyer after the order takes place. This container is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.",
+ "$ref": "#/components/schemas/TimeDuration"
+ },
+ "merchantLocationKey": {
+ "type": "string",
+ "description": "The unique identifier of a merchant's store where the In-Store Pickup inventory item is currently located, or where inventory will be sent to. If the merchant's store is currently awaiting for inventory, the availabilityType value should be SHIP_TO_STORE. This field is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36"
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "This integer value indicates the quantity of the inventory item that is available for In-Store Pickup at the store identified by the merchantLocationKey value. The value of quantity should be an integer value greater than 0, unless the inventory item is out of stock. This field is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used to specify/indicate the quantity of the inventory item that is available for an In-Store Pickup order at the merchant's physical store (specified by the merchantLocationKey field)."
+ },
+ "PriceQuantity": {
+ "type": "object",
+ "properties": {
+ "offers": {
+ "type": "array",
+ "description": "This container is needed if the seller is updating the price and/or quantity of one or more published offers, and a successful call will actually update the active eBay listing with the revised price and/or available quantity.
This call is not designed to work with unpublished offers. For unpublished offers, the seller should use the updateOffer call to update the available quantity and/or price.
If the seller is also using the shipToLocationAvailability container and sku field to update the total 'ship-to-home' quantity of the inventory item, the SKU value associated with the corresponding offerId value(s) must be the same as the corresponding sku value that is passed in, or an error will occur.
Important! A separate (OfferPriceQuantity) node is required for each offer being updated.
If the seller wants to update the price and/or quantity of one or more offers, and also wants to update the total 'ship-to-home' quantity of the corresponding inventory item, the SKU value associated with the offerId value(s) must be the same as the corresponding sku value that is passed in, or an error will occur.
Use the getInventoryItems method to retrieve SKU values.
Max Length: 50
"
+ }
+ },
+ "description": "This type is used to update the total \"ship-to-home\" quantity for one or more inventory items and/or to update the price and/or quantity of one or more specific offers associated with one or more inventory items."
+ },
+ "PriceQuantityResponse": {
+ "type": "object",
+ "properties": {
+ "errors": {
+ "type": "array",
+ "description": "This array will be returned if there were one or more errors associated with the update to the offer or inventory item record.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "offerId": {
+ "type": "string",
+ "description": "The unique identifier of the offer that was updated. This field will not be returned in situations where the seller is only updating the total 'ship-to-home' quantity of an inventory item record."
+ },
+ "sku": {
+ "type": "string",
+ "description": "This is the seller-defined SKU value of the product. This field is returned whether the seller attempted to update an offer with the SKU value or just attempted to update the total 'ship-to-home' quantity of an inventory item record.
Max Length: 50
"
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "The value returned in this container will indicate the status of the attempt to update the price and/or quantity of the offer (specified in the corresponding offerId field) or the attempt to update the total 'ship-to-home' quantity of an inventory item (specified in the corresponding sku field). For a completely successful update of an offer or inventory item record, a value of 200 will appear in this field. A user can view the HTTP status codes section for information on other status codes that may be returned with the bulkUpdatePriceQuantity method.",
+ "format": "int32"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "This array will be returned if there were one or more warnings associated with the update to the offer or inventory item record.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type is used to display the result for each offer and/or inventory item that the seller attempted to update with a bulkUpdatePriceQuantity call. If any errors or warnings occur, the error/warning data is returned at the offer/inventory item level."
+ },
+ "PricingSummary": {
+ "type": "object",
+ "properties": {
+ "auctionReservePrice": {
+ "description": "This field indicates the lowest price at which the seller is willing to sell an item through an auction listing. Note that setting a Reserve Price will incur a listing fee of $5 or 7.5% of the Reserve Price, whichever is greater. The minimum fee is $5.
Important: This fee is charged regardless of whether or not the item is sold.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "auctionStartPrice": {
+ "description": "This field indicates the minimum bidding price for the auction. The bidding starts at this price.
Note: If the auctionReservePrice is also specified, the value of auctionStartPrice must be lower than the value of auctionReservePrice.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "minimumAdvertisedPrice": {
+ "description": "This container is needed if the Minimum Advertised Price (MAP) feature will be used in the offer. Minimum Advertised Price (MAP) is an agreement between suppliers (or manufacturers (OEM)) and the retailers (sellers) stipulating the lowest price an item is allowed to be advertised at. Sellers can only offer prices below this price through the use of other discounts. The MAP feature is only available to eligible US sellers. This field will be ignored if the seller and or the listing is not eligible for the MAP feature.
This container will be returned by getOffer and getOffers if set for the offer.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "originallySoldForRetailPriceOn": {
+ "type": "string",
+ "description": "This field is needed if the Strikethrough Pricing (STP) feature will be used in the offer. This field indicates that the product was sold for the price in the originalRetailPrice field on an eBay site, or sold for that price by a third-party retailer. When using the createOffer or updateOffer calls, the seller will pass in a value of ON_EBAY to indicate that the product was sold for the originalRetailPrice on an eBay site, or the seller will pass in a value of OFF_EBAY to indicate that the product was sold for the originalRetailPrice through a third-party retailer. This field and the originalRetailPrice field are only applicable if the seller and listing are eligible to use the Strikethrough Pricing feature, a feature which is limited to the US (core site and Motors), UK, Germany, Canada (English and French versions), France, Italy, and Spain sites.
This field will be returned by getOffer and getOffers if set for the offer. For implementation help, refer to eBay API documentation"
+ },
+ "originalRetailPrice": {
+ "description": "This container is needed if the Strikethrough Pricing (STP) feature will be used in the offer. The dollar value passed into this field indicates the original retail price set by the manufacturer (OEM). eBay does not maintain or validate the value supplied here by the seller. The dollar value in this field should always be more than the dollar value in the price container. This field and the originallySoldForRetailPriceOn field are only applicable if the seller and listing are eligible to use the Strikethrough Pricing feature, a feature which is limited to the US (core site and Motors), UK, Germany, Canada (English and French versions), France, Italy, and Spain sites. Compare the originalRetailPrice and the dollar value in the price field to determine the amount of savings to the buyer. This Original Retail Price will have a strikethrough line through for a marketing affect.
This container will be returned by getOffer and getOffers if set for the offer.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "price": {
+ "description": "This is the listing price of the product. A listing price must be specified before publishing an offer, but it is possible to create an offer without a price.
For published offers, this container will always be returned, but for unpublished offers, this container will only be returned if set for the offer.
Important!Publish offer note: This container and its two child fields (currency and value) are required before an offer can be published to create an active listing.
PRE_CHECKOUT. To show the MAP price after the buyer already commits to buy the item, the seller will set this value to DURING_CHECKOUT. This field will be ignored if the seller and/or the listing is not eligible for the MAP feature.
This field will be returned by getOffer and getOffers if set for the offer. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used to specify the listing price for the product and settings for the Minimum Advertised Price and Strikethrough Pricing features. The price field must be supplied before an offer is published, but a seller may create an offer without supplying a price initially. The Minimum Advertised Price feature is only available on the US site. Strikethrough Pricing is available on the US, eBay Motors, UK, Germany, Canada (English and French), France, Italy, and Spain sites."
+ },
+ "Product": {
+ "type": "object",
+ "properties": {
+ "aspects": {
+ "type": "string",
+ "description": "This is a collection of item specifics (aka product aspects) name-value pairs that provide more information about the product and might make it easier for buyers to find. To view required/recommended product aspects/item specifics names (and corresponding values) for a specific eBay category, sellers can use the getItemAspectsForCategory method of the Taxonomy API. Alternatively, sellers can view similar items on eBay.com in the same category to get an idea of what other sellers are using for product aspects/item specifics.
Important! Effective from December 28th, 2024, sellers offering certain rechargeable devices in EU and Northern Ireland markets must comply with the Common Charger Directive (CCD) and list appropriate charger-related aspects and values on their listings. See Common Charger Directive for more information.
Sellers also have the option of specifying an eBay Product ID (ePID) or optionally, a Global Trade Item Number (GTIN) through the corresponding fields in the product container in an attempt to find a product match in the eBay Catalog. If a match is found based on the ePID or GTIN value, the product aspects that are defined for the eBay Catalog product will automatically get picked up by the newly created/updated inventory item.
Below is an example of the proper JSON syntax to use when manually inputting item specifics. Note that one item specific name, such as 'Features', can have more than one value. If an item specific name has more than one value, each value is delimited with a comma.
\"aspects\": {
\"Brand\": [\"GoPro\"],
\"Storage Type\": [\"Removable\"]
}
Note that inventory items that will become part of an inventory item group and multiple-variation listing should have the same attributes that are defined for the inventory item group.
This container will be returned if one or more item specific pairs are defined for the inventory item.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length for Aspect Name: 40
Max Length for Aspect Value: 50"
+ },
+ "brand": {
+ "type": "string",
+ "description": "The brand of the product. This field is often paired with the mpn field to identify a specific product by Manufacturer Part Number. This field is conditionally required if the eBay category requires a Manufacturer Part Number (MPN) value. If eBay is able to find a product match in the eBay Catalog when an eBay Product ID (ePID) or GTIN value (UPC, ISBN, or EAN) is supplied, all product details of that eBay Catalog product is picked up by the inventory item record (including brand) if the createOrReplaceInventoryItem call is successful.
This field is returned if defined for an inventory item. If a brand was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the brand field.
Max Length: 65"
+ },
+ "description": {
+ "type": "string",
+ "description": "The description of the product. The description of an existing inventory item can be added or modified with a createOrReplaceInventoryItem call. The description of an inventory item is automatically populated if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog.
Note that this field is optional but recommended. If a listingDescription field is omitted when creating and publishing a single-variation offer, the text in this field will be used instead. If neither the product.description field for the inventory item nor the listingDescription field for the offer exist, the publishOffer call will fail. If the inventory item will be part of an inventory item group/multiple-variation listing, this field should definitely be used to specify how the corresponding product variation is different (e.g. This is the green, extra-large version of the shirt). However, in the case of an inventory item group, the text in the description field of the inventory item group will become the listing description of the actual eBay listing instead of the text in this field.
Basic HTML tags are supported, including the following tags:- <b>
- <strong>
- <br>
- <ol>
- <ul>
- <li>
- Table tags including <table>, <tr>, <td>, <th>, <thead>, <tfoot>, <tbody>, <caption>, <colgroup>, and <col>
A seller can not use any active content in their listing description. Active content includes animation or video via JavaScript, Flash, plug-ins, or form actions.
This field is returned if defined for an inventory item. If one of the GTIN types (e.g. UPC) was passed in when the inventory item was created/modified and a product match was found in the eBay catalog, product description is one of the details that gets picked up from the catalog product.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length: 4000"
+ },
+ "ean": {
+ "type": "array",
+ "description": "The European Article Number/International Article Number (EAN) for the product. Although an ePID value is preferred when trying to find a product match in the eBay Catalog, this field can also be used in an attempt to find a product match in the eBay Catalog. If a product match is found in the eBay Catalog, the inventory item is automatically populated with available product details such as a title, a product description, product aspects (including the specified EAN value), and a link to any stock image that exists for the catalog product.
This field is returned if defined for an inventory item. If an EAN was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the ean field.Note: If the item is being listed in a category that requires an EAN value, but one doesn't exist for the product, the seller must provide a string indicating that the product identifier is unavailable. This text varies by marketplace. Refer to Product Identifier Text for the specific text based on the listing marketplace.
",
+ "items": {
+ "type": "string"
+ }
+ },
+ "epid": {
+ "type": "string",
+ "description": "The eBay Product Identifier (ePID) for the product. This field can be used to directly identify an eBay Catalog product. Based on its specified ePID value, eBay will search for the product in the eBay Catalog, and if a match is found, the inventory item is automatically populated with available product details such as product title, product description, product aspects, and a link to any stock image that exists for the catalog product.
In an attempt to find a eBay Catalog product match, an ePID value is always preferred over the other product identifiers, since it is possible that one GTIN value can be associated with multiple eBay Catalog products, and if multiple products are found, product details will not be picked up by the Inventory Item object.
Note: When listing in categoryID 173651 (Auto Performance Tuning Devices & Software), the use of catalog products is required. For more information, see Tuning devices and software.
This field is returned if defined for an inventory item."
+ },
+ "imageUrls": {
+ "type": "array",
+ "description": "An array of one or more links to images for the product. URLs must use the \"HTTPS\" protocol. Images can be self-hosted by the seller, or sellers can use the UploadSiteHostedPictures call of the Trading API to upload images to an eBay Picture Server. If successful, the response of the UploadSiteHostedPictures call will contain a full URL to the image on an eBay Picture Server. This is the URL that will be passed in through the imageUrls array. Before an offer can be published, at least one image must exist for the inventory item. In almost any category at no cost, sellers can include up to 24 pictures in one listing. For inventory items that are a part of an inventory item group/multiple-variation listings, a maximum of 12 pictures may be used per inventory item in the group. Motor vehicle listings are an exception. The number of included pictures in motor vehicle listings depend on the selected vehicle package (see Fees for selling vehicles on eBay Motors).
A link to a stock image for a product may automatically be populated for an inventory item if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog.
This container will always be returned for an inventory item that is part of a published offer since a published offer will always have at least one picture, but this container will only be returned if defined for inventory items that are not a part of a published offer.
Important!Publish offer note: This array is required and at least one image URL must be specified before an offer can be published to create an active listing.
This field is returned if defined for an inventory item. If an ISBN was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the isbn field.Note: If the item is being listed in a category that requires an ISBN value, but one doesn't exist for the product, the seller must provide a string indicating that the product identifier is unavailable. This text varies by marketplace. Refer to Product Identifier Text for the specific text based on the listing marketplace.
",
+ "items": {
+ "type": "string"
+ }
+ },
+ "mpn": {
+ "type": "string",
+ "description": "The Manufacturer Part Number (MPN) of a product. This field is paired with the brand field to identify a product. Some eBay categories require MPN values. The getItemAspectsForCategory method in the Taxonomy API can be used to see if a category requires an MPN. The MPN value for a product may automatically be populated for an inventory item if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog.
This field is returned if defined for an inventory item. If an MPN was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the mpn field.Note: If the item is being listed in a category that requires an MPN value, but one doesn't exist for the product, the seller must provide a string indicating that the product identifier is unavailable. This text varies by marketplace. Refer to Product Identifier Text for the specific text based on the listing marketplace.
Max Length: 65"
+ },
+ "subtitle": {
+ "type": "string",
+ "description": "A subtitle is an optional listing feature that allows the seller to provide more information about the product, possibly including keywords that may assist with search results. An additional listing fee will be charged to the seller if a subtitle is used. For more information on using listing subtitles on the US site, see the Adding a subtitle to your listings help page. The subtitle of an existing inventory item can added, modified, or removed with a createOrReplaceInventoryItem call.
Note that the same subtitle text should be used for each inventory item that will be part of an inventory item group, and ultimately become one product variation within a multiple-variation listing.
This field will only be returned if set for an inventory item.
Max Length: 55"
+ },
+ "title": {
+ "type": "string",
+ "description": "The title of an inventory item can be added or modified with a createOrReplaceInventoryItem call. Although not immediately required, a title will be needed before an offer with the inventory item is published. The title of an inventory item is automatically populated if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog. If the inventory item will become part of a single-variation offer, and the listing is not a product-based listing, the text in this field will become the actual listing title for the published offer. However, if the inventory item will become part of a multiple-variation offer, the text in title field of the inventory item group entity will actually become the listing title for the published offer instead, although a title can still be provided for the inventory item, and it will actually become the title of the variation.
This field will always be returned for an inventory item that is part of a published offer since a published offer will always have a listing title, but this field will only be returned if defined for inventory items that are not a part of a published offer.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length: 80"
+ },
+ "upc": {
+ "type": "array",
+ "description": "The Universal Product Code (UPC) value for the product. Although an ePID value is preferred when trying to find a product match in the eBay Catalog, this field can also be used in an attempt to find a product match in the eBay Catalog. If a product match is found in the eBay Catalog, the inventory item is automatically populated with available product details such as a title, a product description, product aspects (including the specified UPC value), and a link to any stock image that exists for the catalog product.
This field is returned if defined for an inventory item. If a UPC was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the upc field.Note: If the item is being listed in a category that requires a UPC value, but one doesn't exist for the product, the seller must provide a string indicating that the product identifier is unavailable. This text varies by marketplace. Refer to Product Identifier Text for the specific text based on the listing marketplace.
",
+ "items": {
+ "type": "string"
+ }
+ },
+ "videoIds": {
+ "type": "array",
+ "description": "An array of one or more videoId values for the product. A video ID is a unique identifier that is automatically created by eBay when a seller successfully uploads a video to eBay using the uploadVideo method of the Media API.
For information on supported marketplaces and platforms, as well as other requirements and limitations of video support, please refer to Managing videos.
Note: Only one video per listing is supported.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This type is used to define the product details, such as a title, a product description, product aspects/item specifics, and links to images for the product. Optionally, in a createOrReplaceInventoryItem call, a seller can pass in an eBay Product Identifier (ePID) or a Global Trade Item Number (GTIN) value, such as an EAN, an ISBN, a UPC, to identify a product to be matched with a product in the eBay Catalog. The information in this type is also returned in the getInventoryItem, getInventoryItems, and bulkGetInventoryItem calls if defined."
+ },
+ "ProductFamilyProperties": {
+ "type": "object",
+ "properties": {
+ "engine": {
+ "type": "string",
+ "description": "Important! The productFamilyProperties container is no longer supported.
Important! The productFamilyProperties container is no longer supported.
Important! The productFamilyProperties container is no longer supported.
Important! The productFamilyProperties container is no longer supported.
Important! The productFamilyProperties container is no longer supported.
Note: This field is for future use."
+ },
+ "ktype": {
+ "type": "string",
+ "description": "This field can be used if the seller knows the K Type Number for the motor vehicle that is to be added to the compatible product list. If this K Type value is found in the eBay product catalog, the motor vehicle properties (e.g. make, model, year, engine, and trim) will automatically get picked up for that motor vehicle.
Only the AU, DE, ES, FR, IT, and UK marketplaces support the use of K Type Numbers."
+ }
+ },
+ "description": "This type is used to identify a motor vehicle that is compatible with the corresponding inventory item (the SKU that is passed in as part of the call URI). The motor vehicle can be identified through an eBay Product ID or a K-Type value. The gtin field (for inputting Global Trade Item Numbers) is for future use only. If a motor vehicle is found in the eBay product catalog, the motor vehicle properties (engine, make, model, trim, and year) will automatically get picked up for that motor vehicle.
Note: Currently, parts compatibility is only applicable for motor vehicles, but it is possible that the Product Compatibility feature is expanded to other (non-vehicle) products in the future."
+ },
+ "ProductSafety": {
+ "type": "object",
+ "properties": {
+ "component": {
+ "type": "string",
+ "description": "This field is used by the seller to provide product safety component information for the listing. For example, component information can include specific warnings related to product safety, such as 'Tipping hazard'.
Note: Component information can only be specified if used with the pictograms and/or statements field; if the component is provided without one or both of these fields, an error will occur.
Max length: 120 characters"
+ },
+ "pictograms": {
+ "type": "array",
+ "description": "An array of comma-separated string values used to provide product safety pictogram(s) for the listing.
If your product shows universal product safety or compliance symbols, please select the values corresponding to the product safety pictograms for display in the product safety section of the listing. The seller specifies the identifier of each pictogram in this field.
Note: For product safety pictograms, use the getProductSafetyLabels method of the Metadata API to find supported values for a specific marketplace/site.
A maximum of 2 pictograms are allowed for product safety.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "statements": {
+ "type": "array",
+ "description": "An array of comma-separated string values used to provide product safety statement(s) for the listing.
If your product shows universal product safety or compliance warnings, please select the values corresponding to the product safety statements for display in the product safety section of the listing. The seller specifies the identifier of each statement in this field.
Note: For product safety statements, use the getProductSafetyLabels method of the Metadata API to find supported values for a specific marketplace/site.
A maximum of 8 statements are allowed for product safety.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This type is used to define the pictograms and statement containers, and the optional component field, that provide product safety and compliance related information."
+ },
+ "PublishByInventoryItemGroupRequest": {
+ "type": "object",
+ "properties": {
+ "inventoryItemGroupKey": {
+ "type": "string",
+ "description": "This is the unique identifier of the inventory item group. All unpublished offers associated with this inventory item group will be published as a multiple-variation listing if the publishByInventoryItemGroup call is successful. The inventoryItemGroupKey identifier is automatically generated by eBay once an inventory item group is created.
To retrieve an inventoryItemGroupKey value, you can use the getInventoryItem method to retrieve an inventory item that is known to be in the inventory item group to publish, and then look for the inventory item group identifier under the groupIds container in the response of that call."
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "This is the unique identifier of the eBay site on which the multiple-variation listing will be published. The marketplaceId enumeration values are found in MarketplaceEnum. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used by the request payload of the publishByInventoryItemGroup call. The identifier of the inventory item group to publish and the eBay marketplace where the listing will be published is needed in the request payload."
+ },
+ "PublishResponse": {
+ "type": "object",
+ "properties": {
+ "listingId": {
+ "type": "string",
+ "description": "The unique identifier of the newly created eBay listing. This field is returned if the single offer (if publishOffer call was used) or group of offers in an inventory item group (if publishOfferByInventoryItemGroup call was used) was successfully converted into an eBay listing."
+ },
+ "warnings": {
+ "type": "array",
+ "description": "This container will contain an array of errors and/or warnings if any occur when a publishOffer or publishOfferByInventoryItemGroup call is made.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type is used by the base response payload of the publishOffer and publishOfferByInventoryItemGroup calls."
+ },
+ "RegionalProductCompliancePolicies": {
+ "type": "object",
+ "properties": {
+ "countryPolicies": {
+ "type": "array",
+ "description": "The array of country-specific product compliance policies to be used by an offer when it is published and converted to a listing.",
+ "items": {
+ "$ref": "#/components/schemas/CountryPolicy"
+ }
+ }
+ },
+ "description": "This type lists regional product compliance policies to be used by an offer when it is published and converted to a listing."
+ },
+ "RegionalTakeBackPolicies": {
+ "type": "object",
+ "properties": {
+ "countryPolicies": {
+ "type": "array",
+ "description": "The array of country-specific take-back policies to be used by an offer when it is published and converted to a listing.",
+ "items": {
+ "$ref": "#/components/schemas/CountryPolicy"
+ }
+ }
+ },
+ "description": "This type lists regional take-back policies to be used by an offer when it is published and converted to a listing."
+ },
+ "Regulatory": {
+ "type": "object",
+ "properties": {
+ "documents": {
+ "type": "array",
+ "description": "This container provides a collection of regulatory documents associated with the listing.
For information on removing one or more files from a listing using the updateOffer method, see Remove documents from listings. .
Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory document information in their eBay listings. For more information on GPSR, see General Product Safety Regulation (GPSR).",
+ "items": {
+ "$ref": "#/components/schemas/Document"
+ }
+ },
+ "energyEfficiencyLabel": {
+ "description": "This container provides information about the energy efficiency for certain durable goods.
Note: This container can be used to provide European energy efficiency (EEK) information for listings in the Tyres and Appliance categories for sellers in the EU and UK, and Smartphones and Tablets categories for sellers in the US, AU, CA, EU, and UK. If no EEK information is specified through this container, it may be retrieved through a third party vendor. For more information, see Energy efficiency information.
Note: Energy efficiency information is not required for all categories. Use the getRegulatoryPolicies method of the Metadata API to return metadata on the eBay categories that recommend or require energy efficiency-related fields.
Important! When providing energy efficiency information on an appliance or smartphones and tablets listing, the energy efficiency rating and range of the item must be specified through the aspects field when creating the inventory item record. Use the getItemAspectsForCategory method of the Taxonomy API to retrieve applicable rating and range values for a specified category.
The statements element is required to complete the Hazmat section of a listing.
The following elements are optional:- pictograms
- signalWord
- component
Note: Hazmat information is not required for all categories. Use the getRegulatoryPolicies method of the Metadata API to return metadata on the eBay categories that recommend or require Hazmat-related fields.",
+ "$ref": "#/components/schemas/Hazmat"
+ },
+ "manufacturer": {
+ "description": "This container provides information about the manufacturer of the item.
Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory manufacturer information in their eBay listings. Manufacturer information is not required for all categories. Use the getRegulatoryPolicies method of the Metadata API to return metadata on the eBay categories that recommend or require manufacturer-related fields. For more information on GPSR, see General Product Safety Regulation (GPSR).",
+ "$ref": "#/components/schemas/Manufacturer"
+ },
+ "productSafety": {
+ "description": "This container is used to provide product safety information for the listing. One of the following elements is required to complete the Product Safety section for a listing: pictograms or statements. The component element is optional.
Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory product safety information in their eBay listings. Product safety information is not required for all categories. Use the getRegulatoryPolicies method of the Metadata API to return metadata on the eBay categories that recommend or require product safety-related fields. For more information on GPSR, see General Product Safety Regulation (GPSR). ",
+ "$ref": "#/components/schemas/ProductSafety"
+ },
+ "repairScore": {
+ "type": "number",
+ "description": "This field represents the repair index for the listing.
The repair index identifies the manufacturer's repair score for a product (i.e., how easy is it to repair the product.) This field is a floating point value between 0.0 (i.e., difficult to repair,) and 10.0 (i.e., easily repaired.)
Note: 0 should not be used as a default value, as it implies the product is not repairable.
The format for repairScore is limited to one decimal place. For example:7.9 and 0.0 are both valid scores5.645 and 2.10 are both invalid scores
Note: Repair score is not applicable to all categories. Use the getExtendedProducerResponsibilityPolicies method of the Metadata API to see where repair score is applicable."
+ },
+ "responsiblePersons": {
+ "type": "array",
+ "description": "This container provides information about the EU-based Responsible Persons or entities associated with the listing.
A maximum of 5 EU Responsible Persons are supported.
Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory Responsible Persons information in their eBay listings. For more information on GPSR, see General Product Safety Regulation (GPSR).",
+ "items": {
+ "$ref": "#/components/schemas/ResponsiblePerson"
+ }
+ }
+ },
+ "description": "Type defining regulatory information that the seller is required to disclose."
+ },
+ "ResponsiblePerson": {
+ "type": "object",
+ "properties": {
+ "addressLine1": {
+ "type": "string",
+ "description": "The first line of the Responsible Person's street address.
Max length: 180 characters"
+ },
+ "addressLine2": {
+ "type": "string",
+ "description": "The second line of the Responsible Person's address. This field is not always used, but can be used for secondary address information such as 'Suite Number' or 'Apt Number'.
Max length: 180 characters"
+ },
+ "city": {
+ "type": "string",
+ "description": "The city of the Responsible Person's street address.
Max length: 64 characters"
+ },
+ "companyName": {
+ "type": "string",
+ "description": "The name of the Responsible Person or entity.
Max length: 100 characters"
+ },
+ "contactUrl": {
+ "type": "string",
+ "description": "The contact URL of the Responsible Person or entity.
Max length: 250 characters"
+ },
+ "country": {
+ "type": "string",
+ "description": "This defines the list of valid country codes, adapted from http://www.iso.org/iso/country_codes, ISO 3166-1 country code. List elements take the following form to identify a two-letter code with a short name in English, a three-digit code, and a three-letter code: For example, the entry for Japan includes Japan, 392, JPN. Short codes provide uniform recognition, avoiding language-dependent country names. The number code is helpful where Latin script may be problematic. Not all listed codes are universally recognized as countries, for example: code AQ is Antarctica, 010, ATA For implementation help, refer to eBay API documentation"
+ },
+ "email": {
+ "type": "string",
+ "description": "The Responsible Person's email address.
Max length: 180 characters"
+ },
+ "phone": {
+ "type": "string",
+ "description": "The Responsible Person's business phone number.
Max length: 64 characters"
+ },
+ "postalCode": {
+ "type": "string",
+ "description": "The postal code of the Responsible Person's street address.
Max length: 9 characters"
+ },
+ "stateOrProvince": {
+ "type": "string",
+ "description": "The state of province of the Responsible Person's street address.
Max length: 64 characters"
+ },
+ "types": {
+ "type": "array",
+ "description": "The type(s) associated with the Responsible Person or entity.
Note: Currently, the only supported value is EUResponsiblePerson. ",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ }
+ },
+ "description": "This type provides information, such as name and contact details, for an EU-based Responsible Person or entity, associated with the product."
+ },
+ "SameDayShippingCutOffTimes": {
+ "type": "object",
+ "properties": {
+ "overrides": {
+ "type": "array",
+ "description": "This container can be used to override the existing cut-off time(s), specified in the weeklySchedule container, for a specific date or date range.",
+ "items": {
+ "$ref": "#/components/schemas/Overrides"
+ }
+ },
+ "weeklySchedule": {
+ "type": "array",
+ "description": "This container is used to specify the weekly schedule for shipping and handling cut-off times. A cut-off time is required for each business day that the fulfillment center operates. Any orders made after the specified cutOffTime on the specified day(s) of the week will be handled on the next day.",
+ "items": {
+ "$ref": "#/components/schemas/WeeklySchedule"
+ }
+ }
+ },
+ "description": "This type is used by the createInventoryLocation call to specify cut-off time(s) for an inventory location, as well as any overrides for these times."
+ },
+ "ShipToLocationAvailability": {
+ "type": "object",
+ "properties": {
+ "availabilityDistributions": {
+ "type": "array",
+ "description": "This container is used to set the available quantity of the inventory item at one or more warehouse locations.
This container will be returned if available quantity is set for one or more inventory locations.",
+ "items": {
+ "$ref": "#/components/schemas/AvailabilityDistribution"
+ }
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "This container is used to set the total 'ship-to-home' quantity of the inventory item that will be available for purchase through one or more published offers.
This field represents the total quantity of the item that is available for sale across all marketplaces. To update the available quantity allocated to a specific marketplace, use the availableQuantity field in the offer container associated with that marketplace.
Note: To ensure that the available quantity allocated to a specific marketplace doesn't exceed the total available stock, the quantity specified on a listing will be the minimum value between this field and the availableQuantity field.
If an existing inventory item is being updated, and the 'ship-to-home' quantity already exists for the inventory item record, this field should be included again, even if the value is not changing, or the available quantity data will be lost.
Important! This field is not immediately required, but 'ship-to-home' quantity must be set before an offer of the inventory item can be published.
This container will be returned if the available quantity is set for one or more inventory locations.",
+ "items": {
+ "$ref": "#/components/schemas/AvailabilityDistribution"
+ }
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "Important! Publish offer note: Although this field is not required before an offer can be published to create an active listing, out of stock listings will result if this field is omitted or set to 0.
This field is used to set the total 'ship-to-home' quantity of the inventory item that will be available for purchase through one or more published offers. This field is not immediately required, but 'ship-to-home' quantity must be set before an offer of the inventory item can be published.
If an existing inventory item is being updated, and the 'ship-to-home' quantity already exists for the inventory item record, this field should be included again, even if the value is not changing, or the available quantity data will be lost.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used to specify the total 'ship-to-home' quantity of the inventory items that will be available for purchase through one or more published offers."
+ },
+ "ShippingCostOverride": {
+ "type": "object",
+ "properties": {
+ "additionalShippingCost": {
+ "description": "The dollar value passed into this field will override the additional shipping cost that is currently set for the applicable shipping service option. The \"Additional shipping cost\" is the cost to ship each additional identical product to the buyer using the corresponding shipping service. The shipping service option in the fulfillment policy to override is controlled by the shippingServiceType and priority values.
If using an updateOffer call, and this field is defined for the offer being updated, this field must be supplied again, even if its value is not changing.
This field is returned in the getOffer and getOffers calls if defined.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "priority": {
+ "type": "integer",
+ "description": "The integer value input into this field, along with the shippingServiceType value, sets which domestic or international shipping service option in the fulfillment policy will be modified with updated shipping costs. Specifically, the shippingCostOverrides.shippingServiceType value in a createOffer or updateOffer call must match the shippingOptions.optionType value in a fulfillment listing policy, and the shippingCostOverrides.priority value in a createOffer or updateOffer call must match the shippingOptions.shippingServices.sortOrderId value in a fulfillment listing policy.
This field is always required when overriding the shipping costs of a shipping service option, and will be always be returned for each shipping service option whose costs are being overridden.",
+ "format": "int32"
+ },
+ "shippingCost": {
+ "description": "The dollar value passed into this field will override the shipping cost that is currently set for the applicable shipping service option. This value will be the cost to ship one item to the buyer using the corresponding shipping service. The shipping service option in the fulfillment policy to override is controlled by the shippingServiceType and priority values.
If using an updateOffer call, and this field is defined for the offer being updated, this field must be supplied again, even if its value is not changing.
This field is returned in the getOffer and getOffers calls if defined.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "shippingServiceType": {
+ "type": "string",
+ "description": "This enumerated value indicates whether the shipping service specified in the priority field is a domestic or an international shipping service option. To override the shipping costs for a specific domestic shipping service in the fulfillment listing policy, this field should be set to DOMESTIC, and to override the shipping costs for each international shipping service, this field should be set to INTERNATIONAL. This value, along with priority value, sets which domestic or international shipping service option in the fulfillment policy that will be modified with updated shipping costs. Specifically, the shippingCostOverrides.shippingServiceType value in a createOffer or updateOffer call must match the shippingOptions.optionType value in a fulfillment listing policy, and the shippingCostOverrides.priority value in a createOffer or updateOffer call must match the shippingOptions.shippingServices.sortOrderId value in a fulfillment listing policy.
This field is always required when overriding the shipping costs of a shipping service option, and will be always be returned for each shipping service option whose costs are being overridden. For implementation help, refer to eBay API documentation"
+ },
+ "surcharge": {
+ "description": " Note: DO NOT USE THIS FIELD. Shipping surcharges for shipping service options can no longer be set with fulfillment business policies. To set a shipping surcharge for a shipping service option, only the Shipping rate tables tool in My eBay can be used.
The dollar value passed into this field will override the shipping surcharge that is currently set for the applicable shipping service option. The shipping service option in the fulfillment policy to override is controlled by the shippingServiceType and priority values.
If using an updateOffer call, and this field is defined for the offer being updated, this field must be supplied again, even if its value is not changing.
This field is returned in the getOffer and getOffers calls if defined.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type is used if the seller wants to override the shipping costs or surcharge associated with a specific domestic or international shipping service option defined in the fulfillment listing policy that is being applied toward the offer. The shipping-related costs that can be overridden include the shipping cost to ship one item, the shipping cost to ship each additional item (if multiple quantity are purchased), and the shipping surcharge applied to the shipping service option."
+ },
+ "SpecialHours": {
+ "type": "object",
+ "properties": {
+ "date": {
+ "type": "string",
+ "description": "A date value is required for each specific date that the store location has special operating hours or is closed for that date.
The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2025-08-04T00:00:00.000Z
This field is returned if set for the store location."
+ },
+ "intervals": {
+ "type": "array",
+ "description": "This array is used to set the operating hours for the date specified in the corresponding date field. These special operating hours on this specific date will override the normal operating hours for that day of the week that is specified through the operatingHours array.
To specify a location as closed on the corresponding date, include the intervals array as empty.
If a location closes for lunch (or any other period during the day) and then reopens, multiple open and close pairs are needed to specify each interval where the location is open.
This container is returned if set for the store location.",
+ "items": {
+ "$ref": "#/components/schemas/Interval"
+ }
+ }
+ },
+ "description": "This type is used to express the special operating hours of a store location on a specific date. A specialHours container is needed when the store's opening hours on a specific date are different than the normal operating hours on that particular day of the week."
+ },
+ "Specification": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "This is the name of product variation aspect. Typically, for clothing, typical aspect names are \"Size\" and \"Color\". Product variation aspects are not required immediately upon creating an inventory item group, but these aspects will be required before a multiple-variation listing containing this inventory item group is published. For each product variation aspect that is specified through the specifications container, one name value is required and two or more variations of this aspect are required through the values array.
Note: Each member of the inventory item group should have these same aspect names specified through the product.aspects container when the inventory item is created with the createOrReplaceInventoryItem or bulkCreateOrReplaceInventoryItem call.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length: 40"
+ },
+ "values": {
+ "type": "array",
+ "description": "This is an array of values pertaining to the corresponding product variation aspect (specified in the name field). Below is a sample of how these values will appear under a specifications container:
\"specifications\": [{
\"name\": \"Size\",
\"values\": [\"Small\",
\"Medium\",
\"Large\"]
},
{
\"name\": \"Color\",
\"values\": [\"Blue\",
\"White\",
\"Red\"]
}]
Note: Each member of the inventory item group should have these same aspect names, and each individual inventory item should have each variation of the product aspect values specified through the product.aspects container when the inventory item is created with the createOrReplaceInventoryItem or bulkCreateOrReplaceInventoryItem call.
Important!Publish offer note: This array is required and at least one value that matches the corresponding aspect name must be specified.
Max Length: 50",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This type is used to specify product aspects for which variations within an inventory item group vary, and the order in which they appear in the listing. For example, t-shirts in an inventory item group may be available in multiple sizes and colors."
+ },
+ "Tax": {
+ "type": "object",
+ "properties": {
+ "applyTax": {
+ "type": "boolean",
+ "description": "When set to true, the seller's account-level sales-tax table will be used to calculate sales tax for an order.
Note: Sales-tax tables are available only for the US and Canada marketplaces.
Important! In the US, eBay now calculates, collects, and remits sales tax to the proper taxing authorities in all 50 states and Washington, DC. Sellers can no longer specify sales-tax rates for these jurisdictions using a tax table.
However, sellers may continue to use a sales-tax table to set rates for the following US territories:
- American Samoa (AS)
- Guam (GU)
- Northern Mariana Islands (MP)
- Palau (PW)
- US Virgin Islands (VI)
For complete information about using sales-tax tables, refer to Establishing sales-tax tables.
Note that a seller can enable the use of a sales-tax table, but if a sales-tax rate is not specified for the buyer's tax jurisdiction, sales tax will not be applied to the order.
When a thirdPartyTaxCategory value is used, applyTax must also be set to true.
This field will be returned by getOffer and getOffers if set for the offer.
For additional information, refer to Taxes and import charges."
+ },
+ "thirdPartyTaxCategory": {
+ "type": "string",
+ "description": "The tax exception category code. If this field is used, sales tax will also apply to a service/fee, and not just the item price. This is to be used only by sellers who have opted into sales tax being calculated by a sales tax calculation vendor. If you are interested in becoming a tax calculation vendor partner with eBay, contact developer-relations@ebay.com. One supported value for this field is WASTE_RECYCLING_FEE. If this field is used, the applyTax field must also be used and set to true
This field will be returned by getOffer and getOffers if set for the offer."
+ },
+ "vatPercentage": {
+ "type": "number",
+ "description": "This value is the Value Add Tax (VAT) rate for the item, if any. When a VAT percentage is specified, the item's VAT information appears on the listing's View Item page. In addition, the seller can choose to print an invoice that includes the item's net price, VAT percent, VAT amount, and total price. Since VAT rates vary depending on the item and on the user's country of residence, a seller is responsible for entering the correct VAT rate; it is not calculated by eBay.
To use VAT, a seller must be a business seller with a VAT-ID registered with eBay, and must be listing the item on a VAT-enabled site. Max applicable length is 6 characters, including the decimal (e.g., 12.345). The scale is 3 decimal places. (If you pass in 12.3456, eBay may round up the value to 12.346).
This field will be returned by getOffer and getOffers if set for the offer."
+ }
+ },
+ "description": "This type is used to enable the use of a sales-tax table, to pass in a tax exception category code, or to specify a VAT percentage.
Note: Sales-tax tables are available only for the US and Canada marketplaces."
+ },
+ "TimeDuration": {
+ "type": "object",
+ "properties": {
+ "unit": {
+ "type": "string",
+ "description": "This enumeration value indicates the time unit used to specify the fulfillment time, such as BUSINESS_DAY. For implementation help, refer to eBay API documentation"
+ },
+ "value": {
+ "type": "integer",
+ "description": "The integer value in this field, along with the time unit in the unit field, will indicate the fulfillment time.
For standard orders that will be shipped, this value will indicate the expected fulfillment time if the inventory item is shipped from the inventory location. If the value of this field is 4, and the value of the unit field is BUSINESS_DAY, then the estimated delivery date after purchase is 4 business days.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used to indicate the fulfillment time for an In-Store Pickup order, or for an order than will be shipped to the buyer."
+ },
+ "VariesBy": {
+ "type": "object",
+ "properties": {
+ "aspectsImageVariesBy": {
+ "type": "array",
+ "description": "This container is used if the seller wants to include multiple images to demonstrate how variations within a multiple-variation listing differ. In this string field, the seller will specify the product aspect where the variations of the inventory item group vary, such as color. If Color is specified in this field, Color must also be one of the specifications.name values, and all available colors must appear in the corresponding specifications.values array.
If the aspectsImageVariesBy container is used, links to images of each variation should be specified through the imageUrls container of the inventory item group, or the seller can choose to include those links to images in each inventory item record for the inventory items in the group.
Important!Publish offer note: This array is required and at least one aspect (such as Color) must be specified before an offer can be published to create an active listing.
If a product aspect is specified in the aspectsImageVariesBy container, this product aspect (along with all variations of that product aspect) must be included in the specifications container. Before offers related to the inventory item group are published, the product aspects and values specified through the specifications container should be in synch with the name-value pairs specified through the product.aspects containers of the inventory items contained in the group. For example, if Color and Size are in this specifications container, each inventory item of the group should also have Color and Size as aspect names in their inventory item records.
This container is always returned if one or more offers associated with the inventory item group have been published. For inventory item groups that have yet to have any published offers, this container is only returned if set.
Important!Publish offer note: This array is required and at least one aspect with the available variations must be specified.
Cut-off times default to the time zone of the specified address if the timeZoneId is not provided.
Note: If cut-off hours are not specified for a particular day, the fulfillment center is considered to be on holiday for that day.
Format: 00:00"
+ },
+ "dayOfWeekEnum": {
+ "type": "array",
+ "description": "This comma-separated array defines the days of week for which the specified cutOffTime is used.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ }
+ },
+ "description": "This type describes the weekly schedule for cut-off times."
+ },
+ "Weight": {
+ "type": "object",
+ "properties": {
+ "unit": {
+ "type": "string",
+ "description": "The unit of measurement used to specify the weight of a shipping package. Both the unit and value fields are required if the weight container is used. If the English system of measurement is being used, the applicable values for weight units are POUND and OUNCE. If the metric system of measurement is being used, the applicable values for weight units are KILOGRAM and GRAM. The metric system is used by most countries outside of the US. For implementation help, refer to eBay API documentation"
+ },
+ "value": {
+ "type": "number",
+ "description": "The actual weight (in the measurement unit specified in the unit field) of the shipping package. Both the unit and value fields are required if the weight container is used. If a shipping package weighed 20.5 ounces, the container would look as follows:
\"weight\": {
\"value\": 20.5,
\"unit\": \"OUNCE\"
}"
+ }
+ },
+ "description": "This type is used to specify the weight (and the unit used to measure that weight) of a shipping package. The weight container is conditionally required if the seller will be offering calculated shipping rates to determine shipping cost, or is using flat-rate costs, but charging a weight surcharge. See the Calculated shipping help page for more information on calculated shipping."
+ },
+ "WithdrawByInventoryItemGroupRequest": {
+ "type": "object",
+ "properties": {
+ "inventoryItemGroupKey": {
+ "type": "string",
+ "description": "This is the unique identifier of the inventory item group. This identifier is automatically generated by eBay once an inventory item group is created.
To retrieve an inventoryItemGroupKey value, you can use the getInventoryItem method to retrieve an inventory item that is known to be in the inventory item group to publish, and then look for the inventory item group identifier under the groupIds container in the response of that call."
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "This is the unique identifier of the eBay site for which the offer will be made available. See MarketplaceEnum for supported values. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used by the base request of the WithdrawByInventoryItemGroup method, which is used to end a multiple-variation listing."
+ },
+ "WithdrawResponse": {
+ "type": "object",
+ "properties": {
+ "listingId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay listing associated with the offer that was withdrawn. This field will not be returned if the eBay listing was not successfully ended."
+ },
+ "warnings": {
+ "type": "array",
+ "description": "This container will be returned if there were one or more warnings associated with the attempt to withdraw the offer.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "The base response of the withdrawOffer call."
+ }
+ },
+ "securitySchemes": {
+ "api_auth": {
+ "type": "oauth2",
+ "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
+ "flows": {
+ "authorizationCode": {
+ "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
+ "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
+ "scopes": {
+ "https://api.ebay.com/oauth/api_scope/sell.inventory": "View and manage your inventory and offers",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly": "View your inventory and offers"
+ }
+ }
}
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- }
- },
- "components": {
- "schemas": {
- "Address": {
- "type": "object",
- "properties": {
- "addressLine1": {
- "type": "string",
- "description": "The first line of a street address. This field is required for store and fulfillment center locations. A street address is not required for warehouse locations.
This field will be returned if defined for an inventory location.
Max length: 128"
- },
- "addressLine2": {
- "type": "string",
- "description": "The second line of a street address. This field can be used for additional address information, such as a suite or apartment number.
This field will be returned if defined for an inventory location.
Max length: 128"
- },
- "city": {
- "type": "string",
- "description": "The city in which the inventory location resides. This field is required for store and fulfillment center locations. For warehouse locations, this field is conditionally required as part of a city and stateOrProvince pair if a postalCode is not provided. If a postalCode is provided, the city is derived from the provided postal code and this field is technically optional.
This field is returned if defined for an inventory location.
Max length: 128"
- },
- "country": {
- "type": "string",
- "description": "The country in which the address resides, represented as two-letter ISO 3166 country code. For example, US represents the United States, and DE represents Germany. For implementation help, refer to eBay API documentation"
- },
- "county": {
- "type": "string",
- "description": "The county in which the address resides.
This field is returned if defined for an inventory location."
- },
- "postalCode": {
- "type": "string",
- "description": "The postal/zip code of the address. eBay uses postal codes to surface In-Store Pickup items within the vicinity of a buyer's location, and it also uses postal codes (origin and destination) to estimate shipping costs when the seller uses calculated shipping. This field is required for store and fulfillment center locations.
For warehouse locations, this field is conditionally required if a city and stateOrProvince pair is not provided.
Note: For warehouse locations, city and stateOrProvince pair can be used instead of a postalCode value, and then the postal code is just derived from the city and state/province.
This field is returned if defined for an inventory location.
Max length: 16"
- },
- "stateOrProvince": {
- "type": "string",
- "description": "The state/province in which the inventory location resides. This field is required for store and fulfillment center locations. For warehouse locations, this field is conditionally required as part of a city and stateOrProvince pair if a postalCode is not provided. If a postalCode is provided, the state or province is derived from the provided zip code and this field is technically optional.
Max length: 128"
- }
- },
- "description": "This type is used to define the physical address of an inventory location."
- },
- "Amount": {
- "type": "object",
- "properties": {
- "currency": {
- "type": "string",
- "description": "A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices.
See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values."
- },
- "value": {
- "type": "string",
- "description": "A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices."
- }
- },
- "description": "This type is used to express a dollar value and the applicable currency."
- },
- "Availability": {
- "type": "object",
- "properties": {
- "pickupAtLocationAvailability": {
- "type": "array",
- "description": "This container consists of an array of one or more of the merchant's physical store locations where the inventory item is available for In-Store Pickup orders. The merchant's location, the quantity available, and the fulfillment time (how soon the item will be ready for pickup after the order takes place) are all in this container. In-Store Pickup is only available to large merchants selling on the US, UK, Germany, and Australia sites.",
- "items": {
- "$ref": "#/components/schemas/PickupAtLocationAvailability"
- }
- },
- "shipToLocationAvailability": {
- "description": "This container specifies the quantity of the inventory item that are available for purchase across one or more eBay marketplaces.",
- "$ref": "#/components/schemas/ShipToLocationAvailability"
- }
- },
- "description": "This type is used to specify the quantity of the inventory item that is available for purchase if the item will be shipped to the buyer, and the quantity of the inventory item that is available for In-Store Pickup at one or more of the merchant's physical stores. In-Store Pickup is only available to large merchants selling on the US, UK, Germany, and Australia sites."
- },
- "AvailabilityDistribution": {
- "type": "object",
- "properties": {
- "fulfillmentTime": {
- "description": "This container is used to indicate the expected fulfillment time if the inventory item is shipped from the warehouse location identified in the corresponding merchantLocationKey field. The fulfillment time is the estimated number of business days after purchase that the buyer can expect the item to be delivered.
This field is optional, and is used by eBay to provide the estimated delivery date to buyers. This field is returned by getInventoryItem and getInventoryItems if set for the inventory item.",
- "$ref": "#/components/schemas/TimeDuration"
- },
- "merchantLocationKey": {
- "type": "string",
- "description": "The unique identifier of an inventory location where quantity is available for the inventory item. This field is conditionally required to identify the inventory location that has quantity of the inventory item.
Use the getInventoryLocations method to retrieve merchant location keys."
- },
- "quantity": {
- "type": "integer",
- "description": "The integer value passed into this field indicates the quantity of the inventory item that is available at this inventory location. This field is conditionally required.",
- "format": "int32"
- }
- },
- "description": "This type is used to set the available quantity of the inventory item at one or more warehouse locations."
- },
- "AvailabilityWithAll": {
- "type": "object",
- "properties": {
- "pickupAtLocationAvailability": {
- "type": "array",
- "description": "This container consists of an array of one or more of the merchant's physical stores where the inventory item is available for in-store pickup.
The store ID, the quantity available, and the fulfillment time (how soon the item will be ready for pickup after the order occurs) are all returned in this container.",
- "items": {
- "$ref": "#/components/schemas/PickupAtLocationAvailability"
- }
- },
- "shipToLocationAvailability": {
- "description": "This container specifies the quantity of the inventory items that are available for a standard purchase, where the item is shipped to the buyer.",
- "$ref": "#/components/schemas/ShipToLocationAvailabilityWithAll"
- }
- },
- "description": "This type is used to specify the quantity of the inventory items that are available for purchase if the items will be shipped to the buyer, and the quantity of the inventory items that are available for In-Store Pickup at one or more of the merchant's physical stores.
In-Store Pickup is only available to large merchants selling on the US, UK, Germany, and Australia sites."
- },
- "BaseResponse": {
- "type": "object",
- "properties": {
- "warnings": {
- "type": "array",
- "description": "This container will be returned in a call response payload if one or more warnings or errors are triggered when an Inventory API call is made. This container will contain detailed information about the error or warning.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This is the base response of the createOrReplaceInventoryItem, createOrReplaceInventoryItemGroup, and createOrReplaceProductCompatibility calls. A response payload will only be returned for these three calls if one or more errors or warnings occur with the call."
- },
- "BestOffer": {
- "type": "object",
- "properties": {
- "autoAcceptPrice": {
- "description": "This is the price at which Best Offers are automatically accepted. If a buyer submits a Best Offer that is equal to or above this value, the offer is automatically accepted on behalf of the seller. This field is only applicable if the bestOfferEnabled value is set to true.
The price set here must be lower than the current 'Buy it Now' price. This field is only returned by getOffer and getOffers if set.",
- "$ref": "#/components/schemas/Amount"
- },
- "autoDeclinePrice": {
- "description": "This is the price at which Best Offers are automatically declined. If a buyer submits a Best Offer that is equal to or below this value, the offer is automatically declined on behalf of the seller. This field is only applicable if the bestOfferEnabled value is set to true.
The price set here must be lower than the current 'Buy it Now' price and the price set in the autoAcceptPrice field (if used). This field is only returned by getOffer and getOffers if set.",
- "$ref": "#/components/schemas/Amount"
- },
- "bestOfferEnabled": {
- "type": "boolean",
- "description": "This field indicates whether or not the Best Offer feature is enabled for the listing. A seller can enable the Best Offer feature for a listing as long as the category supports the Best Offer feature.
The seller includes this field and sets its value to true to enable Best Offer feature.
Note: Best Offer is not available for multi-variation listings."
- }
- },
- "description": "This type is used by the bestOfferTerms container, which is used if the seller would like to support the Best Offer feature on their listing."
- },
- "BulkEbayOfferDetailsWithKeys": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "The details of each offer that is being created is passed in under this container. Up to 25 offers can be created with one bulkCreateOffer call.",
- "items": {
- "$ref": "#/components/schemas/EbayOfferDetailsWithKeys"
- }
- }
- },
- "description": "This type is used by the base request of the bulkCreateOffer method, which is used to create up to 25 new offers."
- },
- "BulkGetInventoryItem": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "The seller passes in multiple SKU values under this container to retrieve multiple inventory item records. Up to 25 inventory item records can be retrieved at one time.",
- "items": {
- "$ref": "#/components/schemas/GetInventoryItem"
- }
- }
- },
- "description": "This type is used by the base request of the bulkGetInventoryItem method."
- },
- "BulkGetInventoryItemResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "This is the base container of the bulkGetInventoryItem response. The results of each attempted inventory item retrieval is captured under this container.",
- "items": {
- "$ref": "#/components/schemas/GetInventoryItemResponse"
- }
- }
- },
- "description": "This type is used by the base response of the bulkGetInventoryItem method."
- },
- "BulkInventoryItem": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "The details of each inventory item that is being created or updated is passed in under this container. Up to 25 inventory item records can be created and/or updated with one bulkCreateOrReplaceInventoryItem call.",
- "items": {
- "$ref": "#/components/schemas/InventoryItemWithSkuLocale"
- }
- }
- },
- "description": "The base request of the bulkCreateOrReplaceInventoryItem method."
- },
- "BulkInventoryItemResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "This is the base container of the bulkCreateOrReplaceInventoryItem response. The results of each attempted inventory item creation/update is captured under this container.",
- "items": {
- "$ref": "#/components/schemas/InventoryItemResponse"
- }
- }
- },
- "description": "This type is used by the base response of the bulkCreateOrReplaceInventoryItem method."
- },
- "BulkMigrateListing": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "This is the base container of the bulkMigrateListings request payload. One to five eBay listings will be included under this container.",
- "items": {
- "$ref": "#/components/schemas/MigrateListing"
- }
- }
- },
- "description": "This type is used by the base container of the bulkMigrateListings request payload."
- },
- "BulkMigrateListingResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "This is the base container of the response payload of the bulkMigrateListings call. The results of each attempted listing migration is captured under this container.",
- "items": {
- "$ref": "#/components/schemas/MigrateListingResponse"
- }
- }
- },
- "description": "This type is used by the response payload of the bulkMigrateListings call."
- },
- "BulkOffer": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "This container is used to pass in an array of offers to publish. Up to 25 offers can be published with one bulkPublishOffer method.",
- "items": {
- "$ref": "#/components/schemas/OfferKeyWithId"
- }
- }
- },
- "description": "This type is used by the base request of the bulkPublishOffer method, which is used to publish up to 25 different offers."
- },
- "BulkOfferResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/OfferSkuResponse"
- }
- }
- },
- "description": "This type is used by the base response of the bulkCreateOffer method."
- },
- "BulkPriceQuantity": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "This container is used by the seller to update the total 'ship-to-home' quantity of one or more inventory items (up to 25) and/or to update the price and/or quantity of one or more specific published offers.",
- "items": {
- "$ref": "#/components/schemas/PriceQuantity"
- }
- }
- },
- "description": "This type is used by the base request payload of the bulkUpdatePriceQuantity call. The bulkUpdatePriceQuantity call allows the seller to update the total 'ship-to-home' quantity of one or more inventory items (up to 25) and/or to update the price and/or quantity of one or more specific published offers."
- },
- "BulkPriceQuantityResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "This container will return an HTTP status code, offer ID, and SKU value for each offer/inventory item being updated, as well as an errors and/or warnings container if any errors or warnings are triggered while trying to update those offers/inventory items.",
- "items": {
- "$ref": "#/components/schemas/PriceQuantityResponse"
- }
- }
- },
- "description": "This type is use by the base response payload of the bulkUpdatePriceQuantity call. The bulkUpdatePriceQuantity call response will return an HTTP status code, offer ID, and SKU value for each offer/inventory item being updated, as well as an errors and/or warnings container if any errors or warnings are triggered while trying to update those offers/inventory items."
- },
- "BulkPublishResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "A node is returned under the responses container to indicate the success or failure of each offer that the seller was attempting to publish.",
- "items": {
- "$ref": "#/components/schemas/OfferResponseWithListingId"
- }
- }
- },
- "description": "This type is used by the base response of the bulkPublishOffer method."
- },
- "Charity": {
- "type": "object",
- "properties": {
- "charityId": {
- "type": "string",
- "description": "The eBay-assigned unique identifier of the charitable organization that will receive a percentage of the sales proceeds. The charitable organization must be reqistered with the PayPal Giving Fund in order to receive sales proceeds through eBay listings.
This field is conditionally required if a seller is planning on donating a percentage of the sale proceeds to a charitable organization.
The eBay-assigned unique identifier of a charitable organization can be found using the getCharityOrgs method of the Charity API. In the getCharityOrgs response, this unique identifier is shown in the charityOrgId field."
- },
- "donationPercentage": {
- "type": "string",
- "description": "This field is the percentage of the purchase price that the charitable organization (identified in the charityId field) will receive for each sale that the listing generates. This field is conditionally required if a seller is planning on donating a percentage of the sale proceeds to a charitable organization. This numeric value can range from 10 to 100, and in any 5 (percent) increments in between this range (e.g. 10, 15, 20...95,... 100). The seller would pass in 10 for 10 percent, 15 for 15 percent, 20 for 20 percent, and so on, all the way to 100 for 100 percent."
- }
- },
- "description": "This type is used to identify the charitable organization associated with the listing, and the percentage of the sale proceeds that the charitable organization will receive for each sale generated by the listing.
In order to receive a percentage of the sales proceeds, the charitable organization must be registered with the PayPal Giving Fund, which is a partner of eBay for Charity."
- },
- "Compatibility": {
- "type": "object",
- "properties": {
- "compatibleProducts": {
- "type": "array",
- "description": "This container consists of an array of motor vehicles (make, model, year, trim, engine) that are compatible with the motor vehicle part or accessory specified by the sku value.",
- "items": {
- "$ref": "#/components/schemas/CompatibleProduct"
- }
- },
- "sku": {
- "type": "string",
- "description": "The seller-defined SKU value of the inventory item that will be associated with the compatible vehicles.
Note: This field is not applicable to the createOrReplaceProductCompatibility method, as the SKU value for the inventory item is passed in as part of the call URI and not in the request payload. It is always returned with the getProductCompatibility method."
- }
- },
- "description": "This type is used by the createOrReplaceProductCompatibility call to associate compatible vehicles to an inventory item. This type is also the base response of the getProductCompatibility call."
- },
- "CompatibleProduct": {
- "type": "object",
- "properties": {
- "compatibilityProperties": {
- "type": "array",
- "description": "This container consists of an array of motor vehicles that are compatible with the motor vehicle part or accessory specified by the SKU value in the call URI. Each motor vehicle is defined through a separate set of name/value pairs. In the name field, the vehicle aspect (such as 'make', 'model', 'year', 'trim', or 'engine') will be identified, and the value field will be used to identify the value of each aspect.
The getCompatibilityProperties method of the Taxonomy API can be used to retrieve applicable vehicle aspect names for a specified category, and the getCompatibilityPropertyValues method of the Taxonomy API can be used to retrieve possible values for these same vehicle aspect names.
Below is an example of identifying one motor vehicle using the compatibilityProperties container:
"compatibilityProperties" : [
{
"name" : "make",
"value" : "Subaru"
},
{
"name" : "model",
"value" : "GL"
},
{
"name" : "year",
"value" : "1983"
},
{
"name" : "trim",
"value" : "Base Wagon 4-Door"
},
{
"name" : "engine",
"value" : "1.8L Turbocharged"
}
]
Typically, the make, model, and year of the motor vehicle are always required, with the trim and engine being necessary sometimes, but it will be dependent on the part or accessory, and on the vehicle class.
Note: The productFamilyProperties container is deprecated and should no longer be used. The compatibilityProperties container should be used instead.",
- "items": {
- "$ref": "#/components/schemas/NameValueList"
- }
- },
- "notes": {
- "type": "string",
- "description": "This field is used by the seller to input any notes pertaining to the compatible vehicle list being defined. The seller might use this field to specify the placement of the part on a vehicle or other applicable information.
This field will only be returned if specified by the seller.
Max Length: 500
"
- },
- "productFamilyProperties": {
- "description": "Important! The productFamilyProperties container is deprecated and should no longer be used. The compatibilityProperties container should be used instead.
Note that this container will not be returned in the getProductCompatibility call.",
- "$ref": "#/components/schemas/ProductIdentifier"
- }
- },
- "description": "This type is used to specify/indicate the motor vehicles that are compatible with the corresponding inventory item. "
- },
- "ConditionDescriptor": {
- "type": "object",
- "properties": {
- "additionalInfo": {
- "type": "string",
- "description": "This string provides additional information about a condition descriptor. Open text is passed in this field.
In the case of trading cards, this field houses the optional Certification Number condition descriptor for graded cards.
Max Length: 30 characters"
- },
- "name": {
- "type": "string",
- "description": "This string provides the name of a condition descriptor. A numeric ID is passed in this field. This numeric ID maps to the name of a condition descriptor. Condition descriptor name-value pairs provide more information about an item's condition in a structured way.
To retrieve all condition descriptor name numeric IDs for a category, refer to the conditionDescriptorId field returned in the getItemConditionPolicies method of Metadata API.
In the case of trading cards, this field is used to provide condition descriptors for a card. For graded cards, the condition descriptors for Grader and Grade are required, while the condition descriptor for Certification Number is optional. For ungraded cards, only the Card Condition condition descriptor is required."
- },
- "values": {
- "type": "array",
- "description": "This array provides the value(s) associated with a condition descriptor. One or more numeric IDs is passed in this field. Commas are used as delimiters between successive name/value pairs. These numeric IDs map to the values associated with a condition descriptor name. Condition descriptor name-value pairs provide more information about an item's condition in a structured way.
To retrieve all condition descriptor value numeric IDs for a category, refer to the ConditionDescriptorValueId array returned in the getItemConditionPolicies method of Metadata API.
In the case of trading cards, this field houses the information on the Grader and Grade descriptors of graded cards and the Card Condition descriptor for ungraded cards.",
- "items": {
- "type": "string"
- }
- }
- },
- "description": "This type is used by the seller to provide additional information about the condition of an item in a structured format."
- },
- "CountryPolicy": {
- "type": "object",
- "properties": {
- "country": {
- "type": "string",
- "description": "The two-letter ISO 3166-1 country code identifying the country to which the policy or policies specified in the corresponding policyIds array will apply. For implementation help, refer to eBay API documentation"
- },
- "policyIds": {
- "type": "array",
- "description": "An array of custom policy identifiers that apply to the country specified by listingPolicies.regionalTakeBackPolicies.countryPolicies.country.
Product compliance and take-back policy information may be returned using the following methods:- getCustomPolicies
Set policy_types to:PRODUCT_COMPLIANCE for product compliance policiesTAKE_BACK for takeback policies
This returns the list of specified policies and corresponding customPolicyId values a seller has created. - getCustomPolicy with
custom_policy_id = customPolicyId
Returns the details of the the policy specified by customPolicyId
For information about creating and managing custom policies, refer to the custom_policy resource in the Sell Account API.",
- "items": {
- "type": "string"
- }
- }
- },
- "description": "This type specifies custom product compliance and/or take-back policies that apply to a specified country."
- },
- "Dimension": {
- "type": "object",
- "properties": {
- "height": {
- "type": "number",
- "description": "The actual height (in the measurement unit specified in the unit field) of the shipping package. All fields of the dimensions container are required if package dimensions are specified.
If a shipping package measured 21.5 inches in length, 15.0 inches in width, and 12.0 inches in height, the dimensions container would look as follows:
\"dimensions\": {
\"length\": 21.5,
\"width\": 15.0,
\"height\": 12.0,
\"unit\": \"INCH\"
}
"
- },
- "length": {
- "type": "number",
- "description": "The actual length (in the measurement unit specified in the unit field) of the shipping package. All fields of the dimensions container are required if package dimensions are specified.
If a shipping package measured 21.5 inches in length, 15.0 inches in width, and 12.0 inches in height, the dimensions container would look as follows:
\"dimensions\": {
\"length\": 21.5,
\"width\": 15.0,
\"height\": 12.0,
\"unit\": \"INCH\"
}
"
- },
- "unit": {
- "type": "string",
- "description": "The unit of measurement used to specify the dimensions of a shipping package. All fields of the dimensions container are required if package dimensions are specified. If the English system of measurement is being used, the applicable values for dimension units are FEET and INCH. If the metric system of measurement is being used, the applicable values for weight units are METER and CENTIMETER. The metric system is used by most countries outside of the US. For implementation help, refer to eBay API documentation"
- },
- "width": {
- "type": "number",
- "description": "The actual width (in the measurement unit specified in the unit field) of the shipping package. All fields of the dimensions container are required if package dimensions are specified.
If a shipping package measured 21.5 inches in length, 15.0 inches in width, and 12.0 inches in height, the dimensions container would look as follows:
\"dimensions\": {
\"length\": 21.5,
\"width\": 15.0,
\"height\": 12.0,
\"unit\": \"INCH\"
}
"
- }
- },
- "description": "This type is used to specify the dimensions (and the unit used to measure those dimensions) of a shipping package. The dimensions container is conditionally required if the seller will be offering calculated shipping rates to determine shipping cost. See the Calculated shipping help page for more information on calculated shipping."
- },
- "Document": {
- "type": "object",
- "properties": {
- "documentId": {
- "type": "string",
- "description": "The unique identifier of a regulatory document associated with the listing.
This value can be found in the response of the createDocument method of the Media API."
- }
- },
- "description": "This type provides an array of one or more regulatory documents associated with a listing for Regulatory Compliance."
- },
- "EbayOfferDetailsWithAll": {
- "type": "object",
- "properties": {
- "availableQuantity": {
- "type": "integer",
- "description": "This integer value indicates the quantity of the inventory item (specified by the sku value) that will be available for purchase by buyers shopping on the eBay site specified in the marketplaceId field.",
- "format": "int32"
- },
- "categoryId": {
- "type": "string",
- "description": "The unique identifier of the primary eBay category that the inventory item is listed under. This field is always returned for published offers, but is only returned if set for unpublished offers."
- },
- "charity": {
- "description": "This container is returned if a charitable organization will receive a percentage of sale proceeds for each sale generated by the listing. This container consists of the charityId field to identify the charitable organization, and the donationPercentage field that indicates the percentage of the sales proceeds that will be donated to the charitable organization.",
- "$ref": "#/components/schemas/Charity"
- },
- "extendedProducerResponsibility": {
- "description": "This container is used to provide the eco-participation fee for a product. Use the getExtendedProducerResponsibilityPoliciesĀ method of theĀ Sell Metadata API to retrieve categories that support eco-participation fee for a specified marketplace.",
- "$ref": "#/components/schemas/ExtendedProducerResponsibility"
- },
- "format": {
- "type": "string",
- "description": "This enumerated value indicates the listing format of the offer. For implementation help, refer to eBay API documentation"
- },
- "hideBuyerDetails": {
- "type": "boolean",
- "description": "This field is returned as true if the private listing feature has been enabled for the offer. Sellers may want to use this feature when they believe that a listing's potential bidders/buyers would not want their obfuscated user IDs (and feedback scores) exposed to other users.
This field is always returned even if not explicitly set in the offer. It defaults to false, so will get returned as false if seller does not set this feature with a 'Create' or 'Update' offer method."
- },
- "includeCatalogProductDetails": {
- "type": "boolean",
- "description": "This field indicates whether or not eBay product catalog details are applied to a listing. A value of true indicates the listing corresponds to the eBay product associated with the provided product identifier. The product identifier is provided in createOrReplaceInventoryItem.Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to 'true' if omitted.
"
- },
- "listing": {
- "description": "For published offers, this container is always returned in the getOffer and getOffers calls, and includes the eBay listing ID associated with the offer, the status of the listing, and the quantity sold through the listing. The listing container is not returned at all for unpublished offers.",
- "$ref": "#/components/schemas/ListingDetails"
- },
- "listingDescription": {
- "type": "string",
- "description": "The description of the eBay listing that is part of the unpublished or published offer. This field is always returned for published offers, but is only returned if set for unpublished offers.
Max Length: 500000 (which includes HTML markup/tags)"
- },
- "listingDuration": {
- "type": "string",
- "description": "This field indicates the number of days that the listing will be active.
This field is returned for both auction and fixed-price listings; however, the value returned for fixed-price listings will always be GTC. The GTC (Good 'Til Cancelled) listings are automatically renewed each calendar month until the seller decides to end the listing.
Note: If the listing duration expires for an auction offer, the listing then becomes available as a fixed-price offer and will be GTC. For implementation help, refer to eBay API documentation"
- },
- "listingPolicies": {
- "description": "This container indicates the listing policies that are applied to the offer. Listing policies include business policies, custom listing policies, and fields that override shipping costs, enable eBay Plus eligibility, or enable the Best Offer feature.
It is required that the seller be opted into Business Policies before being able to create live eBay listings through the Inventory API. Sellers can opt-in to Business Policies through My eBay or by using the Account API's optInToProgram call. Payment, return, and fulfillment listing policies may be created/managed in My eBay or by using the listing policy calls of the sell Account API. The sell Account API can also be used to create and manage custom policies. For more information, see the sell Account API.
For unpublished offers where business policies have yet to be specified, this container will be returned as empty.",
- "$ref": "#/components/schemas/ListingPolicies"
- },
- "listingStartDate": {
- "type": "string",
- "description": "This timestamp is the date/time (in UTC format) that the seller set for the scheduled listing. With the scheduled listing feature, the seller can set a time in the future that the listing will become active, instead of the listing becoming active immediately after a publishOffer call.
For example: 2023-05-30T19:08:00Z.
Scheduled listings do not always start at the exact date/time specified by the seller, but the date/time of the timestamp returned in getOffer/getOffers will be the same as the timestamp passed into a 'Create' or 'Update' offer call.
This field is returned if set for an offer."
- },
- "lotSize": {
- "type": "integer",
- "description": "This field is only applicable and returned if the listing is a lot listing. A lot listing is a listing that has multiple quantity of the same product. An example would be a set of four identical car tires. The integer value in this field is the number of identical items being sold through the lot listing.",
- "format": "int32"
- },
- "marketplaceId": {
- "type": "string",
- "description": "This enumeration value is the unique identifier of the eBay site on which the offer is available, or will be made available. For implementation help, refer to eBay API documentation"
- },
- "merchantLocationKey": {
- "type": "string",
- "description": "The unique identifier of the inventory location. This identifier is set up by the merchant when the inventory location is first created with the createInventoryLocation call. Once this value is set for an inventory location, it can not be modified. To get more information about this inventory location, the getInventoryLocation method can be used, passing in this value at the end of the call URI.
This field is always returned for published offers, but is only returned if set for unpublished offers.
Max length: 36"
- },
- "offerId": {
- "type": "string",
- "description": "The unique identifier of the offer. This identifier is used in many offer-related calls, and it is also used in the bulkUpdatePriceQuantity call."
- },
- "pricingSummary": {
- "description": "This container shows the listing price for the product offer, and if applicable, the settings for the Minimum Advertised Price and Strikethrough Pricing features. The Minimum Advertised Price feature is only available on the US site. Strikethrough Pricing is available on the US, eBay Motors, UK, Germany, Canada (English and French), France, Italy, and Spain sites.
For unpublished offers where pricing information has yet to be specified, this container will be returned as empty.",
- "$ref": "#/components/schemas/PricingSummary"
- },
- "quantityLimitPerBuyer": {
- "type": "integer",
- "description": "This field is only applicable and set if the seller wishes to set a restriction on the purchase quantity of an inventory item per seller. If this field is set by the seller for the offer, then each distinct buyer may purchase up to, but not exceed the quantity in this field. So, if this field's value is 5, each buyer may purchase a quantity of the inventory item between one and five, and the purchases can occur in one multiple-quantity purchase, or over multiple transactions. If a buyer attempts to purchase one or more of these products, and the cumulative quantity will take the buyer beyond the quantity limit, that buyer will be blocked from that purchase.
",
- "format": "int32"
- },
- "regulatory": {
- "description": "This container is used by the seller to provide regulatory information.",
- "$ref": "#/components/schemas/Regulatory"
- },
- "secondaryCategoryId": {
- "type": "string",
- "description": "The unique identifier for a secondary category. This field is applicable if the seller decides to list the item under two categories. Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. A fee may be charged when adding a secondary category to a listing.
Note: You cannot list US eBay Motors vehicles in two categories. However, you can list Parts & Accessories in two categories."
- },
- "sku": {
- "type": "string",
- "description": "This is the seller-defined SKU value of the product in the offer.
Max Length: 50
"
- },
- "status": {
- "type": "string",
- "description": "The enumeration value in this field specifies the status of the offer - either PUBLISHED or UNPUBLISHED. For implementation help, refer to eBay API documentation"
- },
- "storeCategoryNames": {
- "type": "array",
- "description": "This container is returned if the seller chose to place the inventory item into one or two eBay store categories that the seller has set up for their eBay store. The string value(s) in this container will be the full path(s) to the eBay store categories, as shown below:
\"storeCategoryNames\": [
\"/Fashion/Men/Shirts\",
\"/Fashion/Men/Accessories\" ],
",
- "items": {
- "type": "string"
- }
- },
- "tax": {
- "description": "This container is only returned if a sales tax table, a Value-Added Tax (VAT) rate, and/or a tax exception category code was applied to the offer. Only Business Sellers can apply VAT to their listings. It is possible that the applyTax field will be included with a value of true, but a buyer's purchase will not involve sales tax. A sales tax rate must be set up in the seller's sales tax table for the buyer's state/tax jurisdiction in order for that buyer to be subject to sales tax.
See the Using a tax table help page for more information on setting up and using a sales tax table.",
- "$ref": "#/components/schemas/Tax"
- }
- },
- "description": "This type provides details of an offer, and is used by the response payloads of the getOffer and the getOffers calls."
- },
- "EbayOfferDetailsWithId": {
- "type": "object",
- "properties": {
- "availableQuantity": {
- "type": "integer",
- "description": "This integer value sets the quantity of the inventory item that will be available through the offer. Quantity must be set to 1 or more in order for the inventory item to be purchasable. This value should not be more than the quantity that is specified for the inventory item record. For auction listings, this value must be 1.
If this field exists for the current unpublished or published offer, it should be provided again in the updateOffer call, even if the value is not changing. If this particular field is omitted in an updateOffer call, the general available quantity set for the inventory item record may be used instead, and this may not be accurate if the inventory item is being sold across multiple marketplaces.",
- "format": "int32"
- },
- "categoryId": {
- "type": "string",
- "description": "The unique identifier of the eBay category that the inventory item is/will be listed under. This field is not immediately required for an unpublished offer, but will be required before publishing the offer. Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. The seller passes in a query string like \"iPhone 6\", and category ID values for suggested categories are returned in the response.
If this field exists for the current unpublished offer, it should be provided again in the updateOffer call, even if the eBay category is not changing. For a published offer (aka active eBay listing), this field must be provided or an error may occur. The eBay category of an active eBay listing cannot be changed once the listing has one or more sales, or if the listing is scheduled to end in less than 12 hours.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
true if the seller wishes to update a published or unpublished offer with the private listing feature. Alternatively, the seller could also remove the private listing feature (if already set for a published or unpublished offer) by including this field and setting it to false.
Sellers may want to use this option when they believe that a listing's potential bidders/buyers would not want their obfuscated user IDs (and feedback scores) exposed to other users."
- },
- "includeCatalogProductDetails": {
- "type": "boolean",
- "description": "This field indicates whether or not eBay product catalog details are applied to a listing. A value of true indicates the listing corresponds to the eBay product associated with the provided product identifier. The product identifier is provided in createOrReplaceInventoryItem.Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to 'true' if omitted.
"
- },
- "listingDescription": {
- "type": "string",
- "description": "The text in this field is (published offers), or will become (unpublished offers) the description of the eBay listing. This field is not immediately required for an unpublished offer, but will be required before publishing the offer. Note that if the listingDescription field was omitted in the createOffer call for the offer, the offer entity should have picked up the text provided in the product.description field of the inventory item record, or if the inventory item is part of a group, the offer entity should have picked up the text provided in the description field of the inventory item group record.
HTML tags and markup can be used in listing descriptions, but each character counts toward the max length limit.
Note: To ensure that their short listing description is optimized when viewed on mobile devices, sellers should strongly consider using eBay's View Item description summary feature when listing their items. Keep in mind that the 'short' listing description is what prospective buyers first see when they view the listing on a mobile device. The 'full' listing description is also available to mobile users when they click on the short listing description, but the full description is not automatically optimized for viewing in mobile devices, and many users won't even drill down to the full description.
Using HTML div and span tag attributes, this feature allows sellers to customize and fully control the short listing description that is displayed to prospective buyers when viewing the listing on a mobile device. The short listing description on mobile devices is limited to 800 characters, and whenever the full listing description (provided in this field, in UI, or seller tool) exceeds this limit, eBay uses a special algorithm to derive the best possible short listing description within the 800-character limit. However, due to some short listing description content being removed, it is definitely not ideal for the seller, and could lead to a bad buyer experience and possibly to a Significantly not as described (SNAD) case, since the buyer may not get complete details on the item when viewing the short listing description. See the eBay help page for more details on using the HTML div and span tags.
If this field exists for the current unpublished offer, it should be provided again in the updateOffer call, even if the text is not changing. For a published offer (aka active eBay listing), this field must be provided or an error may occur.
Max length: 500000 (which includes HTML markup/tags)"
- },
- "listingDuration": {
- "type": "string",
- "description": "This field indicates the number of days that the listing will be active. For fixed-price listings, this value must be set to GTC, but auction listings support different listing durations.
The GTC (Good 'Til Cancelled) listings are automatically renewed each calendar month until the seller decides to end the listing.
Note: If the listing duration expires for an auction offer without a winning bidder, the listing then becomes available as a fixed-price offer and listing duration will be GTC.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
For implementation help, refer to eBay API documentation"
- },
- "listingPolicies": {
- "description": "This container sets listing policies that will be used to construct the listing. Listing policies include business policies, custom listing policies, and fields that override shipping costs, enable eBay Plus eligibility, or enable the Best Offer feature. This container is not initially required when creating an offer but will become required before the offer can be published. Busines policies (payment, return, fulfillment policies) will always be required before publishing an offer. Other policies, including the seller created compliance policies and seller created take-back policy, will be required as needed by the marketplace, category, or product.
This container is required for updating published offers, regardless of whether or not the business policies are being changed. For an unpublished offer, this field is not necessarily required, but will be required before an offer can be published.
It is required that the seller be opted in to Business Policies before being able to create live eBay listings through the Inventory API. Sellers can opt-in to Business Policies through My eBay or by using the Account API's optInToProgram call. Similarly, payment, return, and fulfillment business policies may be created/managed in My eBay or by using the business policy calls of the Account API.
Important!Publish offer note: This container and a few of its child fields (as noted below) are required before an offer can be published to create an active listing.
",
- "$ref": "#/components/schemas/ListingPolicies"
- },
- "listingStartDate": {
- "type": "string",
- "description": "This field can be used with an unpublished offer if the seller wants to specify a time in the future that the listing will become active on eBay. The timestamp supplied in this field should be in UTC format, and it should be far enough in the future so that the seller will have enough time to publish the listing with the publishOffer method.
For example: 2023-05-30T19:08:00Z.
This field is optional, and it doesn't apply to offers where the corresponding listing is already active. If this field is not provided, the listing starts immediately after a successful publishOffer method."
- },
- "lotSize": {
- "type": "integer",
- "description": "This field is only applicable if the listing is a lot listing. A lot listing is a listing that has multiple quantity of the same item, such as four identical tires being sold as a single offer, or it can be a mixed lot of similar items, such as used clothing items or an assortment of baseball cards. Whether the lot listing involved identical items or a mixed lot, the integer value passed into this field is the total number of items in the lot. Lots can be used for auction and fixed-price listings.",
- "format": "int32"
- },
- "merchantLocationKey": {
- "type": "string",
- "description": "The unique identifier of a merchant's inventory location (where the inventory item in the offer is located).
To get more information about inventory locations, the getInventoryLocations method can be used.br>
Note: This field is not initially required upon first creating an offer, but will become required before an offer can be published.
Max length: 36"
- },
- "pricingSummary": {
- "description": "This container shows the listing price for the product offer, and if applicable, the settings for the Minimum Advertised Price and Strikethrough Pricing features. The Minimum Advertised Price feature is only available on the US site. Strikethrough Pricing is available on the US, eBay Motors, UK, Germany, Canada (English and French), France, Italy, and Spain sites.
This container is required for updating published offers, regardless of whether or not the pricing information is being changed or not. For an unpublished offer, this container is not necessarily required, but an offer price will be required before an offer can be published, and if a pricingSummary container already exists for an unpublished offer, it must be provided again, even if the values are not changing.
Important!Publish offer note: This container and its child container, price, are required before an offer can be published to create an active listing.
5, each buyer may purchase between one to five of these products, and the purchases can occur in one multiple-quantity purchase, or over multiple transactions. If a buyer attempts to purchase one or more of these products, and the cumulative quantity will take the buyer beyond the quantity limit, that buyer will be blocked from that purchase.
If this field currently exists for an unpublished or published offer, it should be provided again in an updateOffer call, even if the value is not changing.
",
- "format": "int32"
- },
- "regulatory": {
- "description": "This container is used by the seller to provide regulatory information.",
- "$ref": "#/components/schemas/Regulatory"
- },
- "secondaryCategoryId": {
- "type": "string",
- "description": "The unique identifier for a secondary category. This field is applicable if the seller decides to list the item under two categories. Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. A fee may be charged when adding a secondary category to a listing.
Note: You cannot list US eBay Motors vehicles in two categories. However, you can list Parts & Accessories in two categories."
- },
- "storeCategoryNames": {
- "type": "array",
- "description": "This container is used if the seller would like to place the inventory item into one or two store categories that the seller has set up for their eBay store. The string value(s) passed in to this container will be the full path(s) to the store categories, as shown below:
\"storeCategoryNames\": [
\"/Fashion/Men/Shirts\",
\"/Fashion/Men/Accessories\" ],
If this field currently exists for an unpublished or published offer, it should be provided again in an updateOffer call, even if the eBay categories are not changing.",
- "items": {
- "type": "string"
- }
- },
- "tax": {
- "description": "This container is only applicable and used if a sales tax table, a Value-Added Tax (VAT) rate, or a tax exception category code will be applied to the offer. Only Business Sellers can apply VAT to their listings. It is possible that the applyTax field will be included with a value of true, but a buyer's purchase will not involve sales tax. A sales tax rate must be set up in the seller's sales tax table for the buyer's state/tax jurisdiction in order for that buyer to be subject to sales tax. Sales tax rates for different jurisdictions can be added/modified in the Payment Preferences section of My eBay, or the seller can use the sales tax calls of the Account API.
If tax information currently exists for an unpublished or published offer, it should be provided again in an updateOffer call, even if none of the tax settings are changing.
See the Using a tax table help page for more information on setting up and using a sales tax table.",
- "$ref": "#/components/schemas/Tax"
- }
- },
- "description": "updateOffer call. Every field that is currently set with the unpublished/published offer must also be passed into the updateOffer call, even those fields whose values are not changing. Note that for published offers, a successful updateOffer call will actually update the active eBay listing with whatever changes were made."
- },
- "EbayOfferDetailsWithKeys": {
- "type": "object",
- "properties": {
- "availableQuantity": {
- "type": "integer",
- "description": "This integer value sets the quantity of the inventory item (specified by the sku value) that will be available for purchase by buyers shopping on the eBay site specified in the marketplaceId field. Quantity must be set to 1 or more in order for the inventory item to be purchasable, but this field is not necessarily required, even for published offers, if the general quantity of the inventory item has already been set in the inventory item record.
For auction listings, this value must be 1.
Note: The availableQuantity field if set here overrides the quantity field set in the inventory item. See the note in Offer fields for details.",
- "format": "int32"
- },
- "categoryId": {
- "type": "string",
- "description": "The unique identifier of the eBay category that the product will be listed under. This field is not immediately required upon creating an offer, but will be required before publishing the offer.
Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. The seller passes in a query string like \"iPhone 6\", and category ID values for suggested categories are returned in the response.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Note: When listing in categoryID 173651 (Auto Performance Tuning Devices & Software), use of catalog products is required. For more information, see Tuning devices and software.
"
- },
- "charity": {
- "description": "This container is used if the seller wishes to select a charitable organization that will receive a percentage of sale proceeds for each sale generated by the eBay listing. This container consists of the charityId field to identify the charitable organization, and the donationPercentage field that indicates the percentage of the sales proceeds that will be donated to the charitable organization for each sale. Both fields in this container are conditionally required for charitable listings.",
- "$ref": "#/components/schemas/Charity"
- },
- "extendedProducerResponsibility": {
- "description": "This container is used to provide the eco-participation fee for a product.
Use the getExtendedProducerResponsibilityPoliciesĀ method of theĀ Sell Metadata API to retrieve categories that support eco-participation fee for a specified marketplace.",
- "$ref": "#/components/schemas/ExtendedProducerResponsibility"
- },
- "format": {
- "type": "string",
- "description": "This enumerated value indicates the listing format of the offer.
Supported values are FIXED_PRICE and AUCTION. For implementation help, refer to eBay API documentation"
- },
- "hideBuyerDetails": {
- "type": "boolean",
- "description": "This field is included and set to true if the seller wishes to create a private listing.
Sellers may want to use this option when they believe that a listing's potential bidders/buyers would not want their obfuscated user IDs (and feedback scores) exposed to other users."
- },
- "includeCatalogProductDetails": {
- "type": "boolean",
- "description": "This field indicates whether or not eBay product catalog details are applied to a listing. A value of true indicates the listing corresponds to the eBay product associated with the provided product identifier. The product identifier is provided in createOrReplaceInventoryItem.
Default: trueNote: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to true if omitted.
"
- },
- "listingDescription": {
- "type": "string",
- "description": "The text in this field is (published offers), or will become (unpublished offers) the description of the eBay listing. This field is not immediately required for an unpublished offer, but will be required before publishing the offer. Note that if the listingDescription field was omitted in the createOffer call for the offer, the offer entity should have picked up the text provided in the product.description field of the inventory item record, or if the inventory item is part of a group, the offer entity should have picked up the text provided in the description field of the inventory item group record.
HTML tags and markup can be used in listing descriptions, but each character counts toward the max length limit.
Note: To ensure that their short listing description is optimized when viewed on mobile devices, sellers should strongly consider using eBay's View Item description summary feature when listing their items. Keep in mind that the 'short' listing description is what prospective buyers first see when they view the listing on a mobile device. The 'full' listing description is also available to mobile users when they click on the short listing description, but the full description is not automatically optimized for viewing in mobile devices, and many users won't even drill down to the full description.
Using HTML div and span tag attributes, this feature allows sellers to customize and fully control the short listing description that is displayed to prospective buyers when viewing the listing on a mobile device. The short listing description on mobile devices is limited to 800 characters, and whenever the full listing description (provided in this field, in UI, or seller tool) exceeds this limit, eBay uses a special algorithm to derive the best possible short listing description within the 800-character limit. However, due to some short listing description content being removed, it is definitely not ideal for the seller, and could lead to a bad buyer experience and possibly to a Significantly not as described (SNAD) case, since the buyer may not get complete details on the item when viewing the short listing description. See the eBay help page for more details on using the HTML div and span tags.
Max length: 500000 (which includes HTML markup/tags)"
- },
- "listingDuration": {
- "type": "string",
- "description": "This field indicates the number of days that the listing will be active. For fixed-price listings, this value must be set to GTC, but auction listings support different listing durations.
The GTC (Good 'Til Cancelled) listings are automatically renewed each calendar month until the seller decides to end the listing.
Note: If the listing duration expires for an auction offer without a winning bidder, the listing then becomes available as a fixed-price offer and listing duration will be GTC.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
For implementation help, refer to eBay API documentation"
- },
- "listingPolicies": {
- "description": "This container sets listing policies that will be used to construct the listing. Listing policies include business policies, custom listing policies, and fields that override shipping costs, enable eBay Plus eligibility, or enable the Best Offer feature. This container is not initially required when creating an offer but will become required before the offer can be published. Busines policies (payment, return, fulfillment policies) will always be required before publishing an offer. Other policies, including the seller created compliance policies and seller created take-back policy, will be required as needed by the marketplace, category, or product.
It is required that the seller be opted into Business Policies before being able to create live eBay listings through the Inventory API. Sellers can opt-in to Business Policies through My eBay or by using the Account API's optInToProgram call. Payment, return, and fulfillment listing policies may be created/managed in My eBay or by using the listing policy calls of the sell Account API. The sell Account API can also be used to create and manage custom policies. For more information, see the sell Account API.
Important!Publish offer note: This container and a few of its child fields (as noted below) are required before an offer can be published to create an active listing.
For example: 2023-05-30T19:08:00Z.
This field is optional. If this field is not provided, the listing starts immediately after a successful publishOffer method."
- },
- "lotSize": {
- "type": "integer",
- "description": "This field is only applicable if the listing is a lot listing. A lot listing is a listing that has multiple quantity of the same item, such as four identical tires being sold as a single offer, or it can be a mixed lot of similar items, such as used clothing items or an assortment of baseball cards. Whether the lot listing involved identical items or a mixed lot, the integer value passed into this field is the total number of items in the lot. Lots can be used for auction and fixed-price listings.",
- "format": "int32"
- },
- "marketplaceId": {
- "type": "string",
- "description": "This enumeration value is the unique identifier of the eBay site for which the offer will be made available. See MarketplaceEnum for the list of supported enumeration values. This field is required. For implementation help, refer to eBay API documentation"
- },
- "merchantLocationKey": {
- "type": "string",
- "description": "The unique identifier of a merchant's inventory location (where the inventory item in the offer is located).
To get more information about inventory locations, the getInventoryLocations method can be used.
Note: This field is not initially required upon first creating an offer, but will become required before an offer can be published.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max length: 36"
- },
- "pricingSummary": {
- "description": "This container shows the listing price for the product offer, and if applicable, the settings for the Minimum Advertised Price and Strikethrough Pricing features. The Minimum Advertised Price feature is only available on the US site. Strikethrough Pricing is available on the US, eBay Motors, UK, Germany, Canada (English and French), France, Italy, and Spain sites.
This container is not initially required upon first creating an offer, but the price of the offer will become required before an offer can be published.
Important!Publish offer note: This container and its child container, price, are required before an offer can be published to create an active listing.
5, each buyer may purchase between one to five of these products, and the purchases can occur in one multiple-quantity purchase, or over multiple transactions. If a buyer attempts to purchase one or more of these products, and the cumulative quantity will take the buyer beyond the quantity limit, that buyer will be blocked from that purchase.
",
- "format": "int32"
- },
- "regulatory": {
- "description": "This container is used by the seller to provide regulatory information.",
- "$ref": "#/components/schemas/Regulatory"
- },
- "secondaryCategoryId": {
- "type": "string",
- "description": "The unique identifier for a secondary category. This field is applicable if the seller decides to list the item under two categories. Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. A fee may be charged when adding a secondary category to a listing.
Note: You cannot list US eBay Motors vehicles in two categories. However, you can list Parts & Accessories in two categories.Note: When listing in categoryID 173651 (Auto Performance Tuning Devices & Software), use of catalog products is required. For more information, see Tuning devices and software.
"
- },
- "sku": {
- "type": "string",
- "description": "The seller-defined SKU value of the product that will be listed on the eBay site (specified in the marketplaceId field). Only one offer (in unpublished or published state) may exist for each sku/marketplaceId/format combination. This field is required.
Use the getInventoryItems method to retrieve SKU values.
Max Length: 50
"
- },
- "storeCategoryNames": {
- "type": "array",
- "description": "This container is used if the seller would like to place the inventory item into one or two eBay store categories that the seller has set up for their eBay store. The string value(s) passed in to this container will be the full path(s) to the eBay store categories, as shown below:
\"storeCategoryNames\": [
\"/Fashion/Men/Shirts\",
\"/Fashion/Men/Accessories\" ],
",
- "items": {
- "type": "string"
- }
- },
- "tax": {
- "description": "This container is applicable and used only if a sales-tax table, a Value-Added Tax (VAT) rate, or a tax exception category code will be applied to the offer. Only Business Sellers can apply VAT to their listings. It is possible that the applyTax field will be included with a value of true, but a buyer's purchase will not involve sales tax.
A sales-tax rate must be set up in the seller's sales-tax table for the buyer's state/tax jurisdiction in order for that buyer to be subject to sales tax. Sales-tax rates for different jurisdictions can be added/modified in the Payment Preferences section of My eBay, or the seller can use the sales tax calls of the Account API.
Note: Sales-tax tables are available only for the US and Canada marketplaces.Refer to Taxes and import charges for more information on setting up and using a sales tax table.",
- "$ref": "#/components/schemas/Tax"
- }
- },
- "description": "This type provides details of an offer, and is used by the base request payload of the createOffer and bulkCreateOffer methods."
- },
- "EnergyEfficiencyLabel": {
- "type": "object",
- "properties": {
- "imageDescription": {
- "type": "string",
- "description": "A brief verbal summary of the information included on the Energy Efficiency Label for an item.
For example, On a scale of A to G the rating is E."
- },
- "imageURL": {
- "type": "string",
- "description": "The URL to the Energy Efficiency Label image that is applicable to an item."
- },
- "productInformationSheet": {
- "type": "string",
- "description": "The URL to the Product Information Sheet that provides complete manufacturer-provided efficiency information about an item."
- }
- },
- "description": "This container provides information about the energy efficiency for certain durable goods."
- },
- "Error": {
- "type": "object",
- "properties": {
- "category": {
- "type": "string",
- "description": "This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors. "
- },
- "domain": {
- "type": "string",
- "description": "The name of the domain in which the error or warning occurred."
- },
- "errorId": {
- "type": "integer",
- "description": "A unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.",
- "format": "int32"
- },
- "inputRefIds": {
- "type": "array",
- "description": "An array of one or more reference IDs which identify the specific request element(s) most closely associated to the error or warning, if any.",
- "items": {
- "type": "string"
- }
- },
- "longMessage": {
- "type": "string",
- "description": "A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem."
- },
- "message": {
- "type": "string",
- "description": "A description of the condition that caused the error or warning."
- },
- "outputRefIds": {
- "type": "array",
- "description": "An array of one or more reference IDs which identify the specific response element(s) most closely associated to the error or warning, if any.",
- "items": {
- "type": "string"
- }
- },
- "parameters": {
- "type": "array",
- "description": "Various warning and error messages return one or more variables that contain contextual information about the error or waring. This is often the field or value that triggered the error or warning.",
- "items": {
- "$ref": "#/components/schemas/ErrorParameter"
- }
- },
- "subdomain": {
- "type": "string",
- "description": "The name of the subdomain in which the error or warning occurred."
- }
- },
- "description": "This type is used to express detailed information on errors and warnings that may occur with a call request."
- },
- "ErrorParameter": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "This type contains the name and value of an input parameter that contributed to a specific error or warning condition."
- },
- "value": {
- "type": "string",
- "description": "This is the actual value that was passed in for the element specified in the name field."
- }
- },
- "description": "This type is used to indicate the parameter field/value that caused an issue with the call request."
- },
- "ExtendedProducerResponsibility": {
- "type": "object",
- "properties": {
- "ecoParticipationFee": {
- "description": "This is the fee paid for new items to the eco-organization (for example, \"eco-organisme\" in France). It is a contribution to the financing of the elimination of the item responsibly.
Note: 0 should not be used as a default value.Minimum: 0.0",
- "$ref": "#/components/schemas/Amount"
- },
- "producerProductId": {
- "type": "string",
- "description": "Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on."
- },
- "productDocumentationId": {
- "type": "string",
- "description": "Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on."
- },
- "productPackageId": {
- "type": "string",
- "description": "Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on."
- },
- "shipmentPackageId": {
- "type": "string",
- "description": "Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on."
- }
- },
- "description": "This type provides IDs for the producer or importer related to the new item, packaging, added documentation, or an eco-participation fee. In some markets, such as in France, this may be the importer of the item."
- },
- "Fee": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "This dollar value in this container is the actual dollar value of the listing fee type specified in the feeType field.",
- "$ref": "#/components/schemas/Amount"
- },
- "feeType": {
- "type": "string",
- "description": "The value returned in this field indicates the type of listing fee that the seller may incur if one or more unpublished offers (offers are specified in the call request) are published on the marketplace specified in the marketplaceId field. Applicable listing fees will often include things such as InsertionFee or SubtitleFee, but many fee types will get returned even when they are 0.0.
See the Standard selling fees help page for more information on listing fees."
- },
- "promotionalDiscount": {
- "description": "The dollar value in this container indicates any eBay promotional discount applied toward the listing fee type specified in the feeType field. If there was no discount applied toward the fee, this container is still returned but its value is 0.0.",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type is used to express expected listing fees that the seller may incur for one or more unpublished offers, as well as any eBay-related promotional discounts being applied toward a specific fee. These fees are the expected cumulative fees per eBay marketplace (which is indicated in the marketplaceId field)."
- },
- "FeeSummary": {
- "type": "object",
- "properties": {
- "fees": {
- "type": "array",
- "description": "This container is an array of listing fees that can be expected to be applied to an offer on the specified eBay marketplace (marketplaceId value). Many fee types will get returned even when they are 0.0.
See the Standard selling fees help page for more information on listing fees.",
- "items": {
- "$ref": "#/components/schemas/Fee"
- }
- },
- "marketplaceId": {
- "type": "string",
- "description": "This is the unique identifier of the eBay site for which listing fees for the offer are applicable. For implementation help, refer to eBay API documentation"
- },
- "warnings": {
- "type": "array",
- "description": "This container will contain an array of errors and/or warnings when a call is made, and errors and/or warnings occur.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type is used to display the expected listing fees for each unpublished offer specified in the request of the getListingFees call."
- },
- "FeesSummaryResponse": {
- "type": "object",
- "properties": {
- "feeSummaries": {
- "type": "array",
- "description": "This container consists of an array of one or more listing fees that the seller can expect to pay for unpublished offers specified in the call request. Many fee types will get returned even when they are 0.0.",
- "items": {
- "$ref": "#/components/schemas/FeeSummary"
- }
- }
- },
- "description": "This type is used by the base response payload for the getListingFees call. "
- },
- "FormatAllocation": {
- "type": "object",
- "properties": {
- "auction": {
- "type": "integer",
- "description": "This integer value indicates the quantity of the inventory item that is reserved for the published auction format offers of the SKU.",
- "format": "int32"
- },
- "fixedPrice": {
- "type": "integer",
- "description": "This integer value indicates the quantity of the inventory item that is available for the fixed-price offers of the SKU.",
- "format": "int32"
- }
- },
- "description": "This type is used to indicate the quantities of the inventory items that are reserved for the different listing formats of the SKU offers."
- },
- "FulfillmentCenterSpecifications": {
- "type": "object",
- "properties": {
- "sameDayShippingCutOffTimes": {
- "description": "Note: This container only applies to listings with same-day handling.
This container specifies cut-off time(s) for order handling (and optionally cut-off overrides) at a fulfillment center location.
For example, if the cut-off time for order handling is 14:00, any orders made after this time will be handled on the next available business day.
Note: Shipping cut-off times must be specified if one of the locationTypes of the inventory location is FULFILLMENT_CENTER.",
- "$ref": "#/components/schemas/SameDayShippingCutOffTimes"
- }
- },
- "description": "This type is used to provide shipping specification details, such as the weekly cut-off schedule for order handling and cut-off override(s), for a fulfillment center location. "
- },
- "GeoCoordinates": {
- "type": "object",
- "properties": {
- "latitude": {
- "type": "number",
- "description": "The latitude (North-South) component of the geographic coordinate. This field is required if a geoCoordinates container is used.
This field is returned if geographical coordinates are set for the location.
Example: 33.089805"
- },
- "longitude": {
- "type": "number",
- "description": "The longitude (East-West) component of the geographic coordinate. This field is required if a geoCoordinates container is used.
This field is returned if geographical coordinates are set for the location.
Example: -88.709822"
- }
- },
- "description": "This type is used to express the Global Positioning System (GPS) latitude and longitude coordinates of an inventory location."
- },
- "GetInventoryItem": {
- "type": "object",
- "properties": {
- "sku": {
- "type": "string",
- "description": "An array of SKU values are passed in under the sku container to retrieve up to 25 inventory item records.
Use the getInventoryItems method to retrieve SKU values."
- }
- },
- "description": "The seller-defined Stock-Keeping Unit (SKU) of each inventory item that the user wants to retrieve is passed in the request of the bulkGetInventoryItem method."
- },
- "GetInventoryItemResponse": {
- "type": "object",
- "properties": {
- "errors": {
- "type": "array",
- "description": "This container will be returned if there were one or more errors associated with retrieving the inventory item record.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "inventoryItem": {
- "description": "This container consists of detailed information on the inventory item specified in the sku field.",
- "$ref": "#/components/schemas/InventoryItemWithSkuLocaleGroupKeys"
- },
- "sku": {
- "type": "string",
- "description": "The seller-defined Stock-Keeping Unit (SKU) of the inventory item. The seller should have a unique SKU value for every product that they sell."
- },
- "statusCode": {
- "type": "integer",
- "description": "The HTTP status code returned in this field indicates the success or failure of retrieving the inventory item record for the inventory item specified in the sku field. See the HTTP status codes table to see which each status code indicates.",
- "format": "int32"
- },
- "warnings": {
- "type": "array",
- "description": "This container will be returned if there were one or more warnings associated with retrieving the inventory item record.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type is used by the response of the bulkGetInventoryItem method to give the status of each inventory item record that the user tried to retrieve."
- },
- "Hazmat": {
- "type": "object",
- "properties": {
- "component": {
- "type": "string",
- "description": "This field is used by the seller to provide component information for the listing. For example, component information can provide the specific material of Hazmat concern.
Max length: 120"
- },
- "pictograms": {
- "type": "array",
- "description": "An array of comma-separated string values listing applicable pictogram code(s) for Hazard Pictogram(s).
If your product contains hazardous substances or mixtures, please select the values corresponding to the hazard pictograms that are stated on your product's Safety Data Sheet. The selected hazard information will be displayed on your listing.
Note: Use the getHazardousMaterialsLabels method in the Metadata API to find supported values for a specific marketplace/site. Refer to Pictogram sample values for additional information.",
- "items": {
- "type": "string"
- }
- },
- "signalWord": {
- "type": "string",
- "description": "This field sets the signal word for hazardous materials in the listing.
If your product contains hazardous substances or mixtures, please select a value corresponding to the signal word that is stated on your product's Safety Data Sheet. The selected hazard information will be displayed on your listing.
Note: Use the getHazardousMaterialsLabels method in the Metadata API to find supported values for a specific marketplace/site. Refer to Signal word information for additional information."
- },
- "statements": {
- "type": "array",
- "description": "An array of comma-separated string values specifying applicable statement code(s) for hazard statement(s) for the listing.
If your product contains hazardous substances or mixtures, please select the values corresponding to the hazard statements that are stated on your product's Safety Data Sheet. The selected hazard information will be displayed on your listing.
Note: Use the getHazardousMaterialsLabels method in the Metadata API to find supported values for a specific marketplace/site. Refer to Hazard statement sample values for additional information.
This field is required if hazardous material information is provided for the listing.",
- "items": {
- "type": "string"
- }
- }
- },
- "description": "This container is used by the seller to provide hazardous material information for the listing.
The statements element is required to complete the hazmat section of a listing.
The following elements are optional:- pictograms
- signalWord
- component
"
- },
- "Interval": {
- "type": "object",
- "properties": {
- "close": {
- "type": "string",
- "description": "The close value is actually the time that the store location closes. Local time (in Military format) is used. So, if a store closed at 8 PM local time, the close time would look like the following: 20:00:00. This field is conditionally required if the intervals container is used to specify working hours or special hours for a store.
This field is returned if set for the store location."
- },
- "open": {
- "type": "string",
- "description": "The open value is actually the time that the store opens. Local time (in Military format) is used. So, if a store opens at 9 AM local time, the close time would look like the following: 09:00:00. This field is conditionally required if the intervals container is used to specify working hours or special hours for a store.
This field is returned if set for the store location."
- }
- },
- "description": "This type is used by the intervals container to define the opening and closing times of a store location's working day. Local time (in Military format) is used, with the following format: hh:mm:ss."
- },
- "InventoryItem": {
- "type": "object",
- "properties": {
- "availability": {
- "description": "This container is used to specify the quantity of the inventory item that are available for purchase.
This container is optional up until the seller is ready to publish an offer with the SKU, at which time it becomes required. Availability data must also be passed if an inventory item is being updated and availability data already exists for that inventory item.
Since an inventory item must have specified quantity before being published in an offer, this container is always returned in the 'Get' calls for SKUs that are part of a published offer. If a SKU is not part of a published offer, this container will only be returned if set for the inventory item.",
- "$ref": "#/components/schemas/Availability"
- },
- "condition": {
- "type": "string",
- "description": "This enumeration value indicates the condition of the item. Supported item condition values will vary by eBay site and category. To see which item condition values that a particular eBay category supports, use the getItemConditionPolicies method of the Metadata API. This method returns condition ID values that map to the enumeration values defined in the ConditionEnum type. The Item condition ID and name values topic in the Selling Integration Guide has a table that maps condition ID values to ConditionEnum values. The getItemConditionPolicies call reference page has more information.
A condition value is optional up until the seller is ready to publish an offer with the SKU, at which time it becomes required for most eBay categories.
Note: The 'Manufacturer Refurbished' item condition is no longer a valid item condition on any eBay marketplace, and to reflect this change, the MANUFACTURER_REFURBISHED value is no longer applicable, and should not be used. With Version 1.13.0, the CERTIFIED_REFURBISHED enumeration value has been introduced, and CR-eligible sellers should make a note to start using CERTIFIED_REFURBISHED from this point forward. For the time being, if the MANUFACTURER_REFURBISHED enum is used in a createOrReplaceInventoryItem method, it will be accepted but automatically converted by eBay to CERTIFIED_REFURBISHED. In the future, the MANUFACTURER_REFURBISHED may start triggering an error if used.
To list an item as 'Certified Refurbished', a seller must be pre-qualified by eBay for this feature. Any seller who is not eligible for this feature will be blocked if they try to create a new listing or revise an existing listing with this item condition.
Any seller that is interested in eligibility requirements to list with 'Certified Refurbished' should see the Certified refurbished program page in Seller Center. Important!For trading card listings in Non-Sport Trading Card Singles (183050), CCG Individual Cards (183454), and Sports Trading Card Singles (261328) categories, sellers must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition. No other item conditions will be accepted. Use of these item conditions require the seller to use the conditionDescriptors array to provide one or more applicable Condition Descriptor name-value pairs. See the conditionDescriptors field description for more information. If these requierments are not followed, publishOffer, updateOffer, bulkPublishOffer, and publishOfferByInventoryItemGroup methods will fail when trying to create new listings.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
NEW, LIKE_NEW, NEW_OTHER, or NEW_WITH_DEFECTS.
The conditionDescription field is available for all eBay categories. If the conditionDescription field is used with an item in one of the new conditions (mentioned in previous paragraph), eBay will simply ignore this field if included, and eBay will return a warning message to the user.
This field should only be used to further clarify the condition of the used item. It should not be used for branding, promotions, shipping, returns, payment or other information unrelated to the condition of the used item. Make sure that the condition value, condition description, listing description, and the item's pictures do not contradict one another.
This field is not always required, but is required if an inventory item is being updated and a condition description already exists for that inventory item.
This field is returned in the getInventoryItem and getInventoryItems calls if a condition description was provided for a used inventory item.
Max Length: 1000."
- },
- "conditionDescriptors": {
- "type": "array",
- "description": "Important!For trading card listings in Non-Sport Trading Card Singles (183050), CCG Individual Cards (183454), and Sports Trading Card Singles (261328) categories, sellers must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition. No other item conditions will be accepted. Use of these item conditions require the seller to use the conditionDescriptors array to provide one or more applicable Condition Descriptor name-value pairs. See the conditionDescriptors field description for more information. If these requierments are not followed, publishOffer, updateOffer, bulkPublishOffer, and publishOfferByInventoryItemGroup methods will fail when trying to create new listings.
This container is used by the seller to provide additional information about the condition of an item in a structured format. Condition descriptors are name-value attributes that can be either closed set or open text inputs.
To retrieve all condition descriptor numeric IDs for a category, use the getItemConditionPolicies method of the Metadata API.
",
- "items": {
- "$ref": "#/components/schemas/ConditionDescriptor"
- }
- },
- "packageWeightAndSize": {
- "description": "This container is used if the seller is offering one or more calculated shipping options for the inventory item, or if the seller is offering flat-rate shipping but is including a shipping surcharge based on the item's weight. This container is used to specify the dimensions and weight of a shipping package.
Note: Package weight and dimensions are only supported for the following marketplaces: AU, CA, DE, IT, UK, US, and Motors. If this information is provided on other marketplaces, it will be ignored.
This container is not always required, but is required if an inventory item is being updated and shipping package data already exists for that inventory item.
This container is returned in the getInventoryItem and getInventoryItems calls if package type, package weight, and/or package dimensions are specified for an inventory item.
See the Calculated shipping help page for more information on calculated shipping.",
- "$ref": "#/components/schemas/PackageWeightAndSize"
- },
- "product": {
- "description": "This container is used to define the product details, such as product title, product description, product identifiers (eBay Product ID, GTIN, or Brand/MPN pair), product aspects/item specifics, and product images. Note that an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) value can be used in an attempt to find a matching product in the eBay Catalog. If a product match is found, the inventory item record will automatically pick up all product details associated with the eBay Catalog product.
Many eBay categories will require at least one product identifier (a GTIN or a Brand/MPN pair). To discover which product identifier(s) that an eBay category might require or support, use the getItemAspectsForCategory method in the Taxonomy API. In the getItemAspectsForCategory response, look for product identifier names (brand, mpn, upc, ean, isbn) in the localizedAspectName fields, and then look for the correspondinng aspectRequired boolean fields as well as the corresponding aspectUsage field, which will indicate if the aspect is required, recommended, or optional. In some cases, a product identifier type may be required, but not known/applicable for a product. If this is the case, the seller must still include the corresponding field in the inventory item record, but pass in a default text string. This text string can vary by site, so the seller should use the GeteBayDetails call of the Trading API to get this string value. In the GeteBayDetails call, the seller should include a DetailName field with its value set to ProductDetails. In the response of the call, the seller can see the default string value in the ProductDetails.ProductIdentifierUnavailableText field. The seller will use this value in one or more of the product identifier fields (ean, isbn, upc, or mpn) if a product ID isn't known or applicable.
This container is not initially required, but it is required before an inventory item can be published as an offer, and/or if an inventory item is being updated and product data already exists for that inventory item.
This container is always returned for published offers in the getInventoryItem, bulkGetInventoryItem, and getInventoryItems calls since product data must be defined for published offers, but for unpublished inventory items, this container will only be returned if product details have been defined for the inventory item.
Important!Publish offer note: This container and a few of its child fields (as noted below) are required before an offer can be published to create an active listing.
\"aspects\": {
\"pattern\": [\"solid\"],
\"sleeves\": [\"short\"]
}
This container is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Note: Since this description will ultimately become the listing description in a multiple-variation listing, the seller should omit the listingDescription field when creating the offers for each variation. If they include the listingDescription field for the individual offer(s) in an item group, the text in that field for a published offer will overwrite the text provided in this description field for the inventory item group.
HTML tags and markup can be used in this field, but each character counts toward the max length limit.
Note: To ensure that their short listing description is optimized when viewed on mobile devices, sellers should strongly consider using eBay's View Item description summary feature when listing their items. Keep in mind that the 'short' listing description is what prospective buyers first see when they view the listing on a mobile device. The 'full' listing description is also available to mobile users when they click on the short listing description, but the full description is not automatically optimized for viewing in mobile devices, and many users won't even drill down to the full description.
Using HTML div and span tag attributes, this feature allows sellers to customize and fully control the short listing description that is displayed to prospective buyers when viewing the listing on a mobile device. The short listing description on mobile devices is limited to 800 characters, and whenever the full listing description (provided in this field, in UI, or seller tool) exceeds this limit, eBay uses a special algorithm to derive the best possible short listing description within the 800-character limit. However, due to some short listing description content being removed, it is definitely not ideal for the seller, and could lead to a bad buyer experience and possibly to a Significantly not as described (SNAD) case, since the buyer may not get complete details on the item when viewing the short listing description. See the eBay help page for more details on using the HTML div and span tags.
This field is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length: 500000 (which includes HTML markup/tags)
"
- },
- "imageUrls": {
- "type": "array",
- "description": "An array of one or more links to images for the inventory item group. URLs must use the \"HTTPS\" protocol. Images can be self-hosted by the seller, or sellers can use the UploadSiteHostedPictures call of the Trading API to upload images to an eBay Picture Server. If successful, the response of the UploadSiteHostedPictures call will contain a full URL to the image on an eBay Picture Server. This is the URL that will be passed in through the imageUrls array.
Note: Before any offer can be published, at least one image must exist for the offer. Links to images can either be passed in through this imageUrls container, or they can be passed in through the product.imageUrls container when creating each inventory item in the group. If the variesBy.aspectsImageVariesBy field is used to specify the main product aspect where the variations vary, the links to the images must be passed in through this imageUrls container, and there should be a picture for each variation. So, if the variesBy.aspectsImageVariesBy field is set to Color, a link should be included to an image demonstrating each available color in the group.
In almost any category at no cost, sellers can include up to 24 pictures in one listing. For inventory items that are a part of an inventory item group/multiple-variation listings, a maximum of 12 pictures may be used per inventory item in the group. Motor vehicle listings are an exception. The number of included pictures in motor vehicle listings depend on the selected vehicle package (see Fees for selling vehicles on eBay Motors).
This container will always be returned for an inventory item group that has at least one published offer since a published offer will always have at least one picture, but this container will only be returned if defined for inventory item groups that have yet to have any published offers. ",
- "items": {
- "type": "string"
- }
- },
- "inventoryItemGroupKey": {
- "type": "string",
- "description": "This is the unique identifier of the inventory item group. This identifier is created by the seller when an inventory item group is created.
Note: This field is only applicable to the getInventoryItemGroup call and not to the createOrReplaceInventoryItemGroup call. In the createOrReplaceInventoryItemGroup call, the inventoryItemGroupKey value is passed into the end of the call URI instead. "
- },
- "subtitle": {
- "type": "string",
- "description": "A subtitle is an optional listing feature that allows the seller to provide more information about the product, possibly including keywords that may assist with search results. An additional listing fee will be charged to the seller if a subtitle is used. For more information on using listing subtitles on the US site, see the Adding a subtitle to your listings help page.
Note: Since this subtitle will ultimately become the subtitle in a multiple-variation listing, the seller should not include the subtitle field when creating the inventory items that are members of the group. If they do include the subtitle field in an inventory item record, the text in that field will overwrite the text provided in this subtitle field for each inventory item in the group that is published.
This field will only be returned if set for an inventory item.
Max Length: 55
"
- },
- "title": {
- "type": "string",
- "description": "The title of the inventory item group. This title will ultimately become the listing title once the first offer of the group is published. This field is not initially required when first creating an inventory item group, but will be required before the first offer of the group is published.
Note: Since this title will ultimately become the listing title in a multiple-variation listing, the seller should omit the title field when creating the inventory items that are members of the group. If they do include the title field in an inventory item record, the text in that field will overwrite the text provided in this title field for each inventory item in the group that is published.
This field is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length: 80
"
- },
- "variantSKUs": {
- "type": "array",
- "description": "This required container is used to assign individual inventory items to the inventory item group. Multiple SKU values are passed in to this container. If updating an existing inventory item group, the seller should make sure that all member SKU values are passed in, as long as the seller wants that SKU to remain in the group.
It is also possible to add or remove SKUs with a createOrReplaceInventoryItemGroup call. If the seller wants to remove a SKU from the group, that seller will just omit that SKU value from this container to remove that inventory item/SKU from the inventory item group and any published, multiple-variation listing. However, a variation cannot be removed from the group if that variation has one or more sales for that listing. A workaround for this is to set that variation's quantity to 0 and it will be 'grayed out' in the View Item page.
This container is always returned.",
- "items": {
- "type": "string"
- }
- },
- "variesBy": {
- "description": "This container is used to specify product aspects for which variations within an inventory item group vary, and a complete list of all those variances. For example, t-shirts in an inventory item group may be available in multiple sizes and colors. If this is the case, Color and Size would both be values in the specifications.name fields, and the available colors and sizes would be values under the corresponding specifications.values array. If the seller will be including multiple images in the listing that will demonstrate how each variation differs, that seller will also include the aspectsImageVariesBy field, and call out the product aspect where the listing images differ. In the t-shirts example, this product aspect would be Color, and the seller could either include URLs to images of the t-shirt (in available colors) through the inventory item group entity, or the seller could also included URLs to images of the t-shirt through the individual inventory item entities of the group.
This container is not initially required when first creating an inventory item group, but the variesBy.specifications container will be required before the first offer of the group is published.
This container is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.
Important!Publish offer note: This container and its child fields (as noted below) are required before an offer can be published to create an active listing.
For information on supported marketplaces and platforms, as well as other requirements and limitations of video support, please refer to Managing videos.
Note: Only one video per listing is supported.",
- "items": {
- "type": "string"
- }
- }
- },
- "description": "This type is used by the base request payload of the createOrReplaceInventoryItemGroup call and the base response payload of the getInventoryItemGroup call."
- },
- "InventoryItemListing": {
- "type": "object",
- "properties": {
- "offerId": {
- "type": "string",
- "description": "Upon a successful migration of a listing, eBay auto-generates this unique identifier, and this offer ID value will be used to retrieve and manage the newly-created offer object. This value will only be generated and returned if the eBay listing is migrated successfully."
- },
- "sku": {
- "type": "string",
- "description": "This is the seller-defined SKU value associated with the item(s) in a listing. This same SKU value will be used to retrieve and manage the newly-created inventory item object if the listing migration is successful. This SKU value will get returned even if the migration is not successful."
- }
- },
- "description": "This type is used by the inventoryItems container that is returned in the response of the bulkMigrateListing call. Up to five sku/offerId pairs may be returned under the inventoryItems container, dependent on how many eBay listings the seller is attempting to migrate to the inventory model."
- },
- "InventoryItemResponse": {
- "type": "object",
- "properties": {
- "errors": {
- "type": "array",
- "description": "This container will be returned if there were one or more errors associated with the creation or update to the inventory item record.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "locale": {
- "type": "string",
- "description": "This field returns the natural language that was provided in the field values of the request payload (i.e., en_AU, en_GB or de_DE). For implementation help, refer to eBay API documentation"
- },
- "sku": {
- "type": "string",
- "description": "The seller-defined Stock-Keeping Unit (SKU) of the inventory item. The seller should have a unique SKU value for every product that they sell."
- },
- "statusCode": {
- "type": "integer",
- "description": "The HTTP status code returned in this field indicates the success or failure of creating or updating the inventory item record for the inventory item indicated in the sku field. See the HTTP status codes table to see which each status code indicates.",
- "format": "int32"
- },
- "warnings": {
- "type": "array",
- "description": "This container will be returned if there were one or more warnings associated with the creation or update to the inventory item record.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type is used by the response of the bulkCreateOrReplaceInventoryItem method to indicate the success or failure of creating and/or updating each inventory item record. The sku value in this type identifies each inventory item record."
- },
- "InventoryItemWithSkuLocale": {
- "type": "object",
- "properties": {
- "availability": {
- "description": "This container is used to specify the quantity of the inventory item that are available for purchase.
Availability data must also be passed if an inventory item is being updated and availability data already exists for that inventory item.
Since an inventory item must have specified quantity before being published in an offer, this container is always returned in the 'Get' calls for SKUs that are part of a published offer. If a SKU is not part of a published offer, this container will only be returned if set for the inventory item. ",
- "$ref": "#/components/schemas/Availability"
- },
- "condition": {
- "type": "string",
- "description": "This enumeration value indicates the condition of the item. Supported item condition values will vary by eBay site and category. To see which item condition values that a particular eBay category supports, use the getItemConditionPolicies method of the Metadata API. This method returns condition ID values that map to the enumeration values defined in the ConditionEnum type. The Item condition ID and name values topic in the Selling Integration Guide has a table that maps condition ID values to ConditionEnum values. The getItemConditionPolicies call reference page has more information.
A condition value is optional up until the seller is ready to publish an offer with the SKU, at which time it becomes required for most eBay categories.
Note: The 'Manufacturer Refurbished' item condition is no longer a valid item condition on any eBay marketplace, and to reflect this change, the MANUFACTURER_REFURBISHED value is no longer applicable, and should not be used. With Version 1.13.0, the CERTIFIED_REFURBISHED enumeration value has been introduced, and CR-eligible sellers should make a note to start using CERTIFIED_REFURBISHED from this point forward. For the time being, if the MANUFACTURER_REFURBISHED enum is used for any of the SKUs in a bulkCreateOrReplaceInventoryItem method, it will be accepted but automatically converted by eBay to CERTIFIED_REFURBISHED.
To list an item as 'Certified Refurbished', a seller must be pre-qualified by eBay for this feature. Any seller who is not eligible for this feature will be blocked if they try to create a new listing or revise an existing listing with this item condition.
Any seller that is interested in eligibility requirements to list with 'Certified Refurbished' should see the Certified refurbished program page in Seller Center. Important!For trading card listings in Non-Sport Trading Card Singles (183050), CCG Individual Cards (183454), and Sports Trading Card Singles (261328) categories, sellers must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition. No other item conditions will be accepted. Use of these item conditions require the seller to use the conditionDescriptors array to provide one or more applicable Condition Descriptor name-value pairs. See the conditionDescriptors field description for more information. If these requierments are not followed, publishOffer, updateOffer, bulkPublishOffer, and publishOfferByInventoryItemGroup methods will fail when trying to create new listings.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
NEW, LIKE_NEW, NEW_OTHER, or NEW_WITH_DEFECTS.
The conditionDescription field is available for all eBay categories. If the conditionDescription field is used with an item in one of the new conditions (mentioned in previous paragraph), eBay will simply ignore this field if included, and eBay will return a warning message to the user.
This field should only be used to further clarify the condition of the used item. It should not be used for branding, promotions, shipping, returns, payment or other information unrelated to the condition of the used item. Make sure that the condition value, condition description, listing description, and the item's pictures do not contradict one another.
This field is not always required, but is required if an inventory item is being updated and a condition description already exists for that inventory item.
This field is returned in the getInventoryItem, bulkGetInventoryItem, and getInventoryItems calls if a condition description was provided for a used inventory item.
Max Length: 1000"
- },
- "conditionDescriptors": {
- "type": "array",
- "description": "Important!For trading card listings in Non-Sport Trading Card Singles (183050), CCG Individual Cards (183454), and Sports Trading Card Singles (261328) categories, sellers must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition. No other item conditions will be accepted. Use of these item conditions require the seller to use the conditionDescriptors array to provide one or more applicable Condition Descriptor name-value pairs. See the conditionDescriptors field description for more information. If these requierments are not followed, publishOffer, updateOffer, bulkPublishOffer, and publishOfferByInventoryItemGroup methods will fail when trying to create new listings.
This container is used by the seller to provide additional information about the condition of an item in a structured format. Condition descriptors are name-value attributes that can be either closed set or open text inputs.
To retrieve all condition descriptor numeric IDs for a category, use the getItemConditionPolicies method of the Metadata API.
",
- "items": {
- "$ref": "#/components/schemas/ConditionDescriptor"
- }
- },
- "locale": {
- "type": "string",
- "description": "This request parameter sets the natural language that was provided in the field values of the request payload (i.e., en_AU, en_GB or de_DE). For implementation help, refer to eBay API documentation"
- },
- "packageWeightAndSize": {
- "description": "This container is used if the seller is offering one or more calculated shipping options for the inventory item, or if the seller is offering flat-rate shipping but is including a shipping surcharge based on the item's weight. This container is used to specify the dimensions and weight of a shipping package.
Note: Package weight and dimensions are only supported for the following marketplaces: AU, CA, DE, IT, UK, US, and Motors. If this information is provided on other marketplaces, it will be ignored.
This container is not always required, but is required if an inventory item is being updated and shipping package data already exists for that inventory item.
This container is returned in the getInventoryItem, bulkGetInventoryItem, and getInventoryItems calls if package type, package weight, and/or package dimensions are specified for an inventory item.
See the Calculated shipping help page for more information on calculated shipping.",
- "$ref": "#/components/schemas/PackageWeightAndSize"
- },
- "product": {
- "description": "This container is used to define the product details, such as product title, product description, product identifiers (eBay Product ID, GTIN, or Brand/MPN pair), product aspects/item specifics, and product images. Note that an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) value can be used in an attempt to find a matching product in the eBay Catalog. If a product match is found, the inventory item record will automatically pick up all product details associated with the eBay Catalog product.
Many eBay categories will require at least one product identifier (a GTIN or a Brand/MPN pair). To discover which product identifier(s) that an eBay category might require or support, use the getItemAspectsForCategory method in the Taxonomy API. In the getItemAspectsForCategory response, look for product identifier names (brand, mpn, upc, ean, isbn) in the localizedAspectName fields, and then look for the correspondinng aspectRequired boolean fields as well as the corresponding aspectUsage field, which will indicate if the aspect is required, recommended, or optional. In some cases, a product identifier type may be required, but not known/applicable for a product. If this is the case, the seller must still include the corresponding field in the inventory item record, but pass in a default text string. This text string can vary by site, so the seller should use the GeteBayDetails call of the Trading API to get this string value. In the GeteBayDetails call, the seller should include a DetailName field with its value set to ProductDetails. In the response of the call, the seller can see the default string value in the ProductDetails.ProductIdentifierUnavailableText field. The seller will use this value in one or more of the product identifier fields (ean, isbn, upc, or mpn) if a product ID isn't known or applicable.
This container is not initially required, but it is required before an inventory item can be published as an offer, and/or if an inventory item is being updated and product data already exists for that inventory item.
This container is always returned for published offers in the getInventoryItem, bulkGetInventoryItem, and getInventoryItems calls since product data must be defined for published offers, but for unpublished inventory items, this container will only be returned if product details have been defined for the inventory item.
Important!Publish offer note: This container and a few of its child fields (as noted below) are required before an offer can be published to create an active listing.
Max Length: 50
"
- }
- },
- "description": "This type is used to define/modify each inventory item record that is being created and/or updated with the bulkCreateOrReplaceInventoryItem method. Up to 25 inventory item records can be created and/or updated with one call."
- },
- "InventoryItemWithSkuLocaleGroupKeys": {
- "type": "object",
- "properties": {
- "availability": {
- "description": "This container shows the quantity of the inventory item that is available for purchase if the item will be shipped to the buyer, and/or the quantity of the inventory item that is available for In-Store Pickup at one or more of the merchant's physical stores.",
- "$ref": "#/components/schemas/AvailabilityWithAll"
- },
- "condition": {
- "type": "string",
- "description": "This enumeration value indicates the condition of the item. Supported item condition values will vary by eBay site and category.
Since the condition of an inventory item must be specified before being published in an offer, this field is always returned in the 'Get' calls for SKUs that are part of a published offer. If a SKU is not part of a published offer, this field will only be returned if set for the inventory item.
Note: The 'Manufacturer Refurbished' item condition is no longer a valid item condition on any eBay marketplace, and to reflect this change, the MANUFACTURER_REFURBISHED value has essentially been replaced with the CERTIFIED_REFURBISHED enumeration value with Version 1.13.0. For any existing inventory items that have MANUFACTURER_REFURBISHED set as their condition value, eBay will automatically convert the condition of these inventory items to CERTIFIED_REFURBISHED, so it is not necessary for the developer to update these inventory items with a 'create or replace' call.
To list an item as 'Certified Refurbished', a seller must be pre-qualified by eBay for this feature. Any seller who is not eligible for this feature will be blocked if they try to create a new listing or revise an existing listing with this item condition.
Any seller that is interested in eligibility requirements to list with 'Certified Refurbished' should see the Certified refurbished program page in Seller Center. Important!For trading card listings in Non-Sport Trading Card Singles (183050), CCG Individual Cards (183454), and Sports Trading Card Singles (261328) categories, LIKE_NEW (2750) can be used to specify the card as a Graded card and USED_VERY_GOOD (4000) can be used to specify the card as an Ungraded card. If either of these item conditions are used for the affected categories, the seller is then required to use the conditionDescriptors array to provide one or more applicable Condition Descriptor name-value pairs. See the conditionDescriptors field description for more information.
Beginning October 23, 2023, trading card listings in the affected categories must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition, and no other item conditions will be accepted. These item conditions and the conditionDescriptors array will be required for all new listings. If not provided after this date, the publishOffer, bulkPublishOffer, and publishOfferByInventoryItemGroup methods will fail when trying to create new listings.
By January 22 2024, all existing listings must be modified with either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition and applicable conditionDescriptors name-value pairs. The updateOffer method will fail if the inventory item object does not have one of these two item conditions along with applicable conditionDescriptors name-value pairs.
Important!For trading card listings in Non-Sport Trading Card Singles (183050), CCG Individual Cards (183454), and Sports Trading Card Singles (261328) categories, LIKE_NEW (2750) can be used to specify the card as a Graded card and USED_VERY_GOOD (4000) can be used to specify the card as an Ungraded card. If either of these item conditions are used for the affected categories, the seller is then required to use the conditionDescriptors array to provide one or more applicable Condition Descriptor name-value pairs.
Beginning October 23, 2023, trading card listings in the affected categories must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition, and no other item conditions will be accepted. These item conditions and the conditionDescriptors array will be required for all new listings. If not provided after this date, the publishOffer, bulkPublishOffer, and publishOfferByInventoryItemGroup methods will fail when trying to create new listings.
By January 22 2024, all existing listings must be modified with either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition and applicable conditionDescriptors name-value pairs. The updateOffer method will fail if the inventory item object does not have one of these two item conditions along with applicable conditionDescriptors name-value pairs.
This container is used by the seller to provide additional information about the condition of an item in a structured format. Descriptors are name-value attributes that can be either closed set or open text.
For more information on the numeric IDs and their text equivalents, use the getItemConditionPolicies method of the Metadata API.
",
- "items": {
- "$ref": "#/components/schemas/ConditionDescriptor"
- }
- },
- "inventoryItemGroupKeys": {
- "type": "array",
- "description": "This array is returned if the inventory item is associated with any inventory item group(s). The value(s) returned in this array are the unique identifier(s) of the inventory item's variation in a multiple-variation listing. This array is not returned if the inventory item is not associated with any inventory item groups.",
- "items": {
- "type": "string"
- }
- },
- "locale": {
- "type": "string",
- "description": "This field returns the natural language that was provided in the field values of the request payload (i.e., en_AU, en_GB or de_DE). For implementation help, refer to eBay API documentation"
- },
- "packageWeightAndSize": {
- "description": "This container is used to specify the dimensions and weight of a shipping package.",
- "$ref": "#/components/schemas/PackageWeightAndSize"
- },
- "product": {
- "description": "This container is used in a createOrReplaceInventoryItem call to pass in a Global Trade Item Number (GTIN) or a Brand and Manufacturer Part Number (MPN) pair to identify a product to be matched with a product in the eBay catalog. If a match is found in the eBay product catalog, the inventory item is automatically populated with available product details such as a title, a subtitle, a product description, item specifics, and links to stock images for the product.",
- "$ref": "#/components/schemas/Product"
- },
- "sku": {
- "type": "string",
- "description": "The seller-defined Stock-Keeping Unit (SKU) of the inventory item. The seller should have a unique SKU value for every product that they sell."
- }
- },
- "description": "This type is used to provide details about each retrieved inventory item record."
- },
- "InventoryItemWithSkuLocaleGroupid": {
- "type": "object",
- "properties": {
- "availability": {
- "description": "This container is used to specify the quantity of the inventory item that are available for purchase if the item will be shipped to the buyer, and the quantity of the inventory item that are available for In-Store Pickup at one or more of the merchant's physical stores",
- "$ref": "#/components/schemas/AvailabilityWithAll"
- },
- "condition": {
- "type": "string",
- "description": "This enumeration value indicates the condition of the item. Supported item condition values will vary by eBay site and category.
Since the condition of an inventory item must be specified before being published in an offer, this field is always returned in the 'Get' calls for SKUs that are part of a published offer. If a SKU is not part of a published offer, this field will only be returned if set for the inventory item.
Note: The 'Manufacturer Refurbished' item condition is no longer a valid item condition on any eBay marketplace, and to reflect this change, the MANUFACTURER_REFURBISHED value has essentially been replaced with the CERTIFIED_REFURBISHED enumeration value with Version 1.13.0. For any existing inventory items that have MANUFACTURER_REFURBISHED set as their condition value, eBay will automatically convert the condition of these inventory items to CERTIFIED_REFURBISHED, so it is not necessary for the developer to update these inventory items with a 'create or replace' call.
To list an item as 'Certified Refurbished', a seller must be pre-qualified by eBay for this feature. Any seller who is not eligible for this feature will be blocked if they try to create a new listing or revise an existing listing with this item condition.
Any seller that is interested in eligibility requirements to list with 'Certified Refurbished' should see the Certified refurbished program page in Seller Center. Important!For trading card listings in Non-Sport Trading Card Singles (183050), CCG Individual Cards (183454), and Sports Trading Card Singles (261328) categories, LIKE_NEW (2750) can be used to specify the card as a Graded card and USED_VERY_GOOD (4000) can be used to specify the card as an Ungraded card. If either of these item conditions are used for the affected categories, the seller is then required to use the conditionDescriptors array to provide one or more applicable Condition Descriptor name-value pairs. See the conditionDescriptors field description for more information.
Beginning October 23, 2023, trading card listings in the affected categories must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition, and no other item conditions will be accepted. These item conditions and the conditionDescriptors array will be required for all new listings. If not provided after this date, the publishOffer, bulkPublishOffer, and publishOfferByInventoryItemGroup methods will fail when trying to create new listings.
By January 22 2024, all existing listings must be modified with either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition and applicable conditionDescriptors name-value pairs. The updateOffer method will fail if the inventory item object does not have one of these two item conditions along with applicable conditionDescriptors name-value pairs.
Max length: 1000"
- },
- "conditionDescriptors": {
- "type": "array",
- "description": "Important!For trading card listings in Non-Sport Trading Card Singles (183050), CCG Individual Cards (183454), and Sports Trading Card Singles (261328) categories, LIKE_NEW (2750) can be used to specify the card as a Graded card and USED_VERY_GOOD (4000) can be used to specify the card as an Ungraded card. If either of these item conditions are used for the affected categories, the seller is then required to use the conditionDescriptors array to provide one or more applicable Condition Descriptor name-value pairs.
Beginning October 23, 2023, trading card listings in the affected categories must use either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition, and no other item conditions will be accepted. These item conditions and the conditionDescriptors array will be required for all new listings. If not provided after this date, the publishOffer, bulkPublishOffer, and publishOfferByInventoryItemGroup methods will fail when trying to create new listings.
By January 22 2024, all existing listings must be modified with either LIKE_NEW (2750) or USED_VERY_GOOD (4000) item condition and applicable conditionDescriptors name-value pairs. The updateOffer method will fail if the inventory item object does not have one of these two item conditions along with applicable conditionDescriptors name-value pairs.
This container is used by the seller to provide additional information about the condition of an item in a structured format. Descriptors are name-value attributes that can be either closed set or open text.
For more information on the numeric IDs and their text equivalents, use the getItemConditionPolicies method of the Metadata API.
",
- "items": {
- "$ref": "#/components/schemas/ConditionDescriptor"
- }
- },
- "groupIds": {
- "type": "array",
- "description": "This array is returned if the inventory item is associated with any inventory item group(s). The value(s) returned in this array are the unique identifier(s) of the inventory item group(s). This array is not returned if the inventory item is not associated with any inventory item groups.",
- "items": {
- "type": "string"
- }
- },
- "inventoryItemGroupKeys": {
- "type": "array",
- "description": "This array is returned if the inventory item is associated with any inventory item group(s). The value(s) returned in this array are the unique identifier(s) of the inventory item's variation in a multiple-variation listing. This array is not returned if the inventory item is not associated with any inventory item groups.",
- "items": {
- "type": "string"
- }
- },
- "locale": {
- "type": "string",
- "description": "This field returns the natural language that was provided in the field values of the request payload (i.e., en_AU, en_GB or de_DE). For implementation help, refer to eBay API documentation"
- },
- "packageWeightAndSize": {
- "description": "This container is used to specify the dimensions and weight of a shipping package.",
- "$ref": "#/components/schemas/PackageWeightAndSize"
- },
- "product": {
- "description": "This container is used in a createOrReplaceInventoryItem call to pass in a Global Trade Item Number (GTIN) or a Brand and Manufacturer Part Number (MPN) pair to identify a product to be matched with a product in the eBay catalog. If a match is found in the eBay product catalog, the inventory item is automatically populated with available product details such as a title, a subtitle, a product description, item specifics, and links to stock images for the product.",
- "$ref": "#/components/schemas/Product"
- },
- "sku": {
- "type": "string",
- "description": "The seller-defined Stock-Keeping Unit (SKU) of the inventory item. The seller should have a unique SKU value for every product that they sell."
- }
- }
- },
- "InventoryItems": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "This is the URL to the current page of inventory items."
- },
- "inventoryItems": {
- "type": "array",
- "description": "This container is an array of one or more inventory items, with detailed information on each inventory item.",
- "items": {
- "$ref": "#/components/schemas/InventoryItemWithSkuLocaleGroupid"
- }
- },
- "limit": {
- "type": "integer",
- "description": "This integer value is the number of inventory items that will be displayed on each results page.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "This is the URL to the next page of inventory items. This field will only be returned if there are additional inventory items to view."
- },
- "prev": {
- "type": "string",
- "description": "This is the URL to the previous page of inventory items. This field will only be returned if there are previous inventory items to view."
- },
- "size": {
- "type": "integer",
- "description": "This integer value indicates the total number of pages of results that are available. This number will depend on the total number of inventory items available for viewing, and on the limit value.",
- "format": "int32"
- },
- "total": {
- "type": "integer",
- "description": "This integer value is the total number of inventory items that exist for the seller's account. Based on this number and on the limit value, the seller may have to toggle through multiple pages to view all inventory items.",
- "format": "int32"
- }
- },
- "description": "This type is used by the base response payload of getInventoryItems call. "
- },
- "InventoryLocation": {
- "type": "object",
- "properties": {
- "location": {
- "description": "This container is used to add any addition physical address and geographical coordinate information for a warehouse, store, or fulfillment center inventory location.
Note: For warehouse and store inventory locations, address fields can be updated any number of times. For fulfilment center locations, address fields cannot be updated. However, if any address fields were omitted during the createInventoryLocation call, they can be added through this method.
Note: When updating a warehouse location to a fulfillment center, sellers can update any of the address fields a single time during the same call used to make this update. After this, they can no longer be updated. ",
- "$ref": "#/components/schemas/LocationDetails"
- },
- "locationAdditionalInformation": {
- "type": "string",
- "description": "This text field is used by the merchant to provide/update additional information about an inventory location. Whatever text is passed in this field will replace the current text string defined for this field. If the text will not change, the same text should be passed in once again.
Max length: 256"
- },
- "locationInstructions": {
- "type": "string",
- "description": "This text field is generally used by the merchant to provide/update special pickup instructions for a store inventory location. Although this field is optional, it is recommended that merchants provide this field to create a pleasant and easy pickup experience for In-Store Pickup and Click and Collect orders. If this field is not included in the call request payload, eBay will use the default pickup instructions contained in the merchant's profile (if available). Whatever text is passed in this field will replace the current text string defined for this field. If the text will not change, the same text should be passed in once again.
Max length: 1000"
- },
- "locationTypes": {
- "type": "array",
- "description": "This container is used to update the location type(s) associated with an inventory location.",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- },
- "locationWebUrl": {
- "type": "string",
- "description": "This text field is used by the merchant to provide/update the Website address (URL) associated with the inventory location. The URL that is passed in this field will replace any other URL that may be defined for this field.
Max length: 512"
- },
- "name": {
- "type": "string",
- "description": "This text field is used by the merchant to update the name of the inventory location. This name should be a human-friendly name as it will be in In-Store Pickup and Click and Collect listings. A name is not required for warehouse locations. For store locations, this field is not immediately required, but will be required before an offer enabled with the In-Store Pickup or Click and Collect capability can be published. So, if the seller omitted this field in the createInventoryLocation call, it is required for an updateInventoryLocation call. The name that is passed in this field will replace any other name that may be defined for this field."
- },
- "operatingHours": {
- "type": "array",
- "description": "This container is used to provide/update the regular operating hours for a store location during the days of the week. A dayOfWeekEnum field and an intervals container will be needed for each day of the week that the location is open. Note that if operating hours are already set for a location for a specific day of the week, whatever is set through an updateInventoryLocation call will override those existing hours.",
- "items": {
- "$ref": "#/components/schemas/OperatingHours"
- }
- },
- "phone": {
- "type": "string",
- "description": "This text field is used by the merchant to provide/update the phone number for the inventory location. The phone number that is passed in this field will replace any other phone number that may be defined for this field.
Max length: 36"
- },
- "specialHours": {
- "type": "array",
- "description": "This container is used to provide/update the special operating hours for a store location on a specific date, such as a holiday. The special hours specified for the specific date will override the normal operating hours for that particular day of the week. If special hours have already been set up for an inventory location, specifying special hours through an updateInventoryLocation call will only add to the list, unless the date(s) used are the same special date(s) already set up, in which case, the special hours set up through the updateInventoryLocation call will override the existing special hours.",
- "items": {
- "$ref": "#/components/schemas/SpecialHours"
- }
- },
- "timeZoneId": {
- "type": "string",
- "description": "This field is used to provide/update the time zone of the inventory location being created. This value should be in Olson format (for example America/Vancouver). For supported values, see Java Supported Zone Ids and Offsets.
Note: If specified, this time zone will be used for all hour related fields. If this field is not specified, the time zone will be calculated from the provided address fields."
- },
- "fulfillmentCenterSpecifications": {
- "description": "This container is used to update information about a fulfillment center's shipping specifications, such as the weekly cut-off time schedule for order handling and any cut-off overrides.",
- "$ref": "#/components/schemas/FulfillmentCenterSpecifications"
- }
- },
- "description": "This type is used by the updateInventoryLocation call to update operating hours, special hours, phone number, and other minor details of an inventory location."
- },
- "InventoryLocationFull": {
- "type": "object",
- "properties": {
- "location": {
- "description": "This required container is used to set the physical address and geographical coordinates of a warehouse, store, or fulfillment center inventory location. A warehouse location only requires the postal code and country OR city, province/state, and country, and does not require a full street address. However, the seller may still supply a full street address for a warehouse location. A complete address (addressLine1, city, stateOrProvince, postalCode, and country) is required for store and fulfillment center locations.
Note: For fulfillment center locations, the addressLine1, stateOrProvince, country and postalCode fields cannot be changed once they have been set, though they can be added through the updateInventoryLocation method if they were omitted during location creation.",
- "$ref": "#/components/schemas/LocationDetails"
- },
- "locationAdditionalInformation": {
- "type": "string",
- "description": "This text field is used by the merchant to provide additional information about an inventory location.
Max length: 256"
- },
- "locationInstructions": {
- "type": "string",
- "description": "This text field is generally used by the merchant to provide special pickup instructions for a store inventory location. Although this field is optional, it is recommended that merchants provide this field to create a pleasant and easy pickup experience for In-Store Pickup and Click and Collect orders. If this field is not included in the call request payload, eBay will use the default pickup instructions contained in the merchant's profile (if available)."
- },
- "locationTypes": {
- "type": "array",
- "description": "This container is used to define the function of the inventory location. Typically, an inventory location will serve as a store, warehouse, or fulfillment center, but in some cases, an inventory location may be more than one type.
For In-Store Pickup inventory, set StoreTypeEnum to STORE.
To utilize the Multi-warehouse program, set StoreTypeEnum to FULFILLMENT_CENTER.
If this container is omitted, the location type of the inventory location will default to WAREHOUSE. See StoreTypeEnum for the supported values.
Default: WAREHOUSE",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- },
- "locationWebUrl": {
- "type": "string",
- "description": "This text field is used by the merchant to provide the Website address (URL) associated with the inventory location.
Max length: 512"
- },
- "merchantLocationStatus": {
- "type": "string",
- "description": "This field is used to indicate whether the inventory location will be enabled (inventory can be loaded to location) or disabled (inventory can not be loaded to location). If this field is omitted, a successful createInventoryLocation call will automatically enable the location. A merchant may want to create a new location but leave it as disabled if the location is not yet ready for active inventory. Once the location is ready, the merchant can use the enableInventoryLocation call to enable a location that is in a disabled state.
See StatusEnum for the supported values.
Default: ENABLED For implementation help, refer to eBay API documentation"
- },
- "name": {
- "type": "string",
- "description": "The seller-defined name of the inventory location. This name should be a human-friendly name as it will be displayed in In-Store Pickup and Click and Collect listings. A name is not required for warehouse locations. For store locations, this field is not immediately required, but will be required before an offer enabled with the In-Store Pickup or Click and Collect capability can be published. So, if the seller omits this field in a createInventoryLocation call, it becomes required for an updateInventoryLocation call.
Max length: 1000"
- },
- "operatingHours": {
- "type": "array",
- "description": "This container is used to express the regular operating hours for a store location during each day of the week. A dayOfWeekEnum field and an intervals container will be needed for each day of the week that the store location is open.
Although not technically required, this container is highly recommended to be used to specify operating hours for a store location.",
- "items": {
- "$ref": "#/components/schemas/OperatingHours"
- }
- },
- "phone": {
- "type": "string",
- "description": "This field is used to specify the phone number for an inventory location.
Max length: 36"
- },
- "specialHours": {
- "type": "array",
- "description": "This container is used to express the special operating hours for a store inventory location on a specific date, such as a holiday. The special hours specified for the specific date will override the normal operating hours for that particular day of the week.",
- "items": {
- "$ref": "#/components/schemas/SpecialHours"
- }
- },
- "timeZoneId": {
- "type": "string",
- "description": "This field specifies the time zone of the inventory location being created. This value should be in Olson format (for example America/Vancouver). For supported values, see Java Supported Zone Ids and Offsets.
Note: If specified, this time zone will be used for all hour related fields. If this field is not specified for a fulfillment center location, the time zone will be calculated from the provided address fields."
- },
- "fulfillmentCenterSpecifications": {
- "description": "This container is used to specify information about a fulfillment center's shipping specifications, such as the weekly cut-off time schedule for order handling and any cut-off time overrides.
Note: This container is required if one of the locationTypes of the inventory location is FULFILLMENT_CENTER, and is not applicable to other location types.",
- "$ref": "#/components/schemas/FulfillmentCenterSpecifications"
- }
- },
- "description": "This type is used by the createInventoryLocation call to provide details on the inventory location, including the location's name, physical address, operating hours, special hours, phone number and other details of an inventory location."
- },
- "InventoryLocationResponse": {
- "type": "object",
- "properties": {
- "location": {
- "description": "This container provides location details of an inventory location. The address container will always be returned, but it will not always have a complete street address. Except in the case of a store or fulfillment center location, a full address is not a requirement when setting up an inventory location. The geoCoordinates container will only be returned if the merchant provided geographical coordinates. The locationId field is always returned, but this value is only used internally by eBay.",
- "$ref": "#/components/schemas/Location"
- },
- "locationAdditionalInformation": {
- "type": "string",
- "description": "This text field provides additional information about an inventory location. This field is returned if it is set for the location."
- },
- "locationInstructions": {
- "type": "string",
- "description": "This text field is used by the merchant to provide special pickup instructions for the store location. This field can help create a pleasant and easy pickup experience for In-Store Pickup and Click and Collect orders. If this field was not set up through a createInventoryLocation or a updateInventoryLocation call, eBay will use the default pickup instructions contained in the merchant's profile."
- },
- "locationTypes": {
- "type": "array",
- "description": "This container defines the function of the inventory location. Typically, a location will serve as a store, warehouse, or fulfillment center, but in some cases, an inventory location may be more than one type.",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- },
- "locationWebUrl": {
- "type": "string",
- "description": "This text field shows the Website address (URL) associated with the inventory location. This field is returned if defined for the location."
- },
- "merchantLocationKey": {
- "type": "string",
- "description": "The unique identifier of the inventory location. This identifier is set up by the merchant when the location is first created with the createInventoryLocation call."
- },
- "merchantLocationStatus": {
- "type": "string",
- "description": "This field indicates whether the inventory location is enabled (inventory can be loaded to location) or disabled (inventory can not be loaded to location). The merchant can use the enableInventoryLocation call to enable a location in disabled status, or the disableInventoryLocation call to disable a location in enabled status. For implementation help, refer to eBay API documentation"
- },
- "name": {
- "type": "string",
- "description": "The name of the inventory location. This name should be a human-friendly name as it will be displayed in In-Store Pickup and Click and Collect listings. For store inventory locations, this field is not required for the createInventoryLocation call, but a store inventory location must have a defined name value before an In-Store Pickup and Click and Collect enabled offer is published. So, if the seller omits this field in the createInventoryLocation call, it will have to be added later through a updateInventoryLocation call."
- },
- "operatingHours": {
- "type": "array",
- "description": "This container shows the regular operating hours for a store location during the days of the week. A dayOfWeekEnum field and an intervals container is shown for each day of the week that the location is open.",
- "items": {
- "$ref": "#/components/schemas/OperatingHours"
- }
- },
- "phone": {
- "type": "string",
- "description": "The phone number for an inventory location. This field will typically only be returned for store locations."
- },
- "specialHours": {
- "type": "array",
- "description": "This container shows the special operating hours for a store or fulfillment center location on a specific date or dates.",
- "items": {
- "$ref": "#/components/schemas/SpecialHours"
- }
- },
- "timeZoneId": {
- "type": "string",
- "description": "This field specifies the time zone of the inventory location being created. This value should be in Olson format (for example America/Vancouver). For supported values, see Java Supported Zone Ids and Offsets."
- },
- "fulfillmentCenterSpecifications": {
- "description": "This container provides information about a fulfillment center's shipping specifications, such as the weekly cut-off time schedule for order handling and any cut-off time overrides.
Note: This field is only returned for fulfillment center locations.",
- "$ref": "#/components/schemas/FulfillmentCenterSpecifications"
- }
- },
- "description": "This type is used by the base response of the getInventoryLocation and getInventoryLocations calls. These responses provide details about inventory location(s) defined for the merchant's account."
- },
- "ListingDetails": {
- "type": "object",
- "properties": {
- "listingId": {
- "type": "string",
- "description": "The unique identifier of the eBay listing that is associated with the published offer. "
- },
- "listingOnHold": {
- "type": "boolean",
- "description": "Indicates if a listing is on hold due to an eBay policy violation.
If a listing is put on hold, users are unable to view the listing details, the listing is hidden from search, and all attempted purchases, offers, and bids for the listing are blocked. eBay, however, gives sellers the opportunity to address violations and get listings fully reinstated. A listing will be ended if a seller does not address a violation, or if the violation can not be rectified.
If a listing is fixable, the seller should be able to view the listing details and this boolean will be returned as true.
Once a listing is fixed, this boolean will no longer be returned.
"
- },
- "listingStatus": {
- "type": "string",
- "description": "The enumeration value returned in this field indicates the status of the listing that is associated with the published offer. For implementation help, refer to eBay API documentation"
- },
- "soldQuantity": {
- "type": "integer",
- "description": "This integer value indicates the quantity of the product that has been sold for the published offer.",
- "format": "int32"
- }
- },
- "description": "This type is used by the listing container in the getOffer and getOffers calls to provide the eBay listing ID, the listing status, and quantity sold for the offer. The listing container is only returned for published offers, and is not returned for unpublished offers."
- },
- "ListingPolicies": {
- "type": "object",
- "properties": {
- "bestOfferTerms": {
- "description": "This container is used if the seller would like to support the Best Offer feature on their listing. To enable the Best Offer feature, the seller will have to set the bestOfferEnabled field to true, and the seller also has the option of setting 'auto-accept' and 'auto-decline' price thresholds.
Note: Best Offer is unavailable for multi-variation listings.
This container is only returned if Best Offer is enabled on listing.",
- "$ref": "#/components/schemas/BestOffer"
- },
- "eBayPlusIfEligible": {
- "type": "boolean",
- "description": "This field is included in an offer and set to true if a Top-Rated seller is opted in to the eBay Plus program. With the eBay Plus program, qualified sellers must commit to next-day delivery of the item, and the buyers must have an eBay Plus subscription to be eligible to receive the benefits of this program, which are free, next-day delivery, as well as free returns.
Note: Currently, this program is only available on the Germany and Australian sites.
This field will be returned in the getOffer and getOffers methods if set for the offer."
- },
- "fulfillmentPolicyId": {
- "type": "string",
- "description": "This unique identifier indicates the fulfillment business policy that will be used once an offer is published and converted to an eBay listing. This fulfillment business policy will set all fulfillment-related settings for the eBay listing.
Business policies are not immediately required for offers, but are required before an offer can be published. The seller should review the fulfillment business policy before assigning it to the offer to make sure it is compatible with the inventory item and the offer settings. The seller may also want to review the shipping service costs in the fulfillment policy, and that seller might decide to override the shipping costs for one or more shipping service options by using the shippingCostOverrides container.
Business policies can be created and managed in My eBay or with the Account API. To get a list of all return policies associated with a seller's account on a specific eBay Marketplace, use the Account API's getFulfillmentPolicies method. There are also calls in the Account API to retrieve a fulfillment policy by policy ID or policy name.
This field will be returned in the getOffer and getOffers methods if set for the offer.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Business policies are not immediately required for offers, but are required before an offer can be published. The seller should review the payment business policy to make sure that it is compatible with the marketplace and listing category before assigning it to the offer.
Business policies can be created and managed in My eBay or with the Account API. To get a list of all payment policies associated with a seller's account on a specific eBay Marketplace, use the Account API's getPaymentPolicies method. There are also calls in the Account API to retrieve a payment policy by policy ID or policy name.
This field will be returned in the getOffer and getOffers methods if set for the offer.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Product compliance policies provide buyers with important information and disclosures about products. For example, if you sell batteries and specific disclosures are required to be shared with all potential buyers, your global product compliance policy could contain the required disclosures.
A maximum of six (6) global product compliance policies may apply to each offer.Note: For countries that support country-specific policies, use regionalProductCompliancePolicies to apply them to an offer.",
- "items": {
- "type": "string"
- }
- },
- "regionalProductCompliancePolicies": {
- "description": "A comma-delimited list of unique identifiers indicating the seller-created country-specific product compliance policies that that will be used once an offer is published and converted to a listing.
Product compliance policies provide buyers with important information and disclosures about products. For example, if you sell batteries in a country requiring disclosures that apply only to that country, a country-specific product compliance policy could contain this information.
Each offer may include up to six (6) product compliance policies for each of the following countries:- United Kingdom [GB]
- Germany [DE]
- France [FR]
- Italy [IT]
- Spain [ES]
For example, if a seller offers products in the UK, Germany, and Italy, each of which requires custom product compliance information, up to 18 policies (i.e., 6 policies x 3 countries,) may be included with each offer.Note: Product compliance policies that apply to all countries to which a seller ships are specified using productCompliancePolicyIds.",
- "$ref": "#/components/schemas/RegionalProductCompliancePolicies"
- },
- "regionalTakeBackPolicies": {
- "description": "The list of unique identifiers indicating the seller-created country-specific take-back policies that will be used once an offer is published and converted to a listing. The law in some countries may require sellers to take back a used product when the buyer buys a new product.
Each offer may include one (1) country-specific take-back policy for each of the following countries:- United Kingdom [GB]
- Germany [DE]
- France [FR]
- Italy [IT]
- Spain [ES]
Note: Take-back policies that apply to all countries to which a seller ships are specified using takeBackPolicyId.",
- "$ref": "#/components/schemas/RegionalTakeBackPolicies"
- },
- "returnPolicyId": {
- "type": "string",
- "description": "This unique identifier indicates the return business policy that will be used once an offer is published and converted to an eBay listing. This return business policy will set all return policy settings for the eBay listing.
Note: As a part of Digital Services Act (DSA) requirements, as of April 3, 2023, buyers in the EU must be allowed to return an item within 14 days or more, unless the item is exempt. Where applicable, sellers should update their return policies to reflect this requirement of accepting returns from EU buyers.
Business policies are not immediately required for offers, but are required before an offer can be published. The seller should review the return business policy before assigning it to the offer to make sure it is compatible with the inventory item and the offer settings.
Business policies can be created and managed in My eBay or with the Account API. To get a list of all return policies associated with a seller's account on a specific eBay Marketplace, use the Account API's getReturnPolicies call. There are also calls in the Account API to retrieve a return policy by policy ID or policy name.
This field will be returned in the getOffer and getOffers methods if set for the offer.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
DOMESTIC to override a domestic shipping service option, or to INTERNATIONAL to override an international shipping service option.
A separate ShippingCostOverrides node is needed for each shipping service option whose costs are being overridden. All defined fields of the shippingCostOverrides container should be included, even if the shipping costs and surcharge values are not changing.
The shippingCostOverrides container is returned in the getOffer and getOffers calls if one or more shipping cost overrides are being applied to the fulfillment policy.",
- "items": {
- "$ref": "#/components/schemas/ShippingCostOverride"
- }
- },
- "takeBackPolicyId": {
- "type": "string",
- "description": "This unique identifier indicates the seller-created global take-back policy that will be used once an offer is published and converted to a listing.
One (1) global take-back policy may be specified per offer.
Note: For countries that support country-specific policies, use regionalTakeBackPolicies to apply them to an offer."
- }
- },
- "description": "This type is used to identify business policies including payment, return, and fulfillment policies, as well as to identify custom policies. These policies are, or will be, associated with the listing. Every published offer must have a payment, return, and fulfillment business policy associated with it. Additionally, depending on the country/countries in which sellers are offering products and/or services to consumers (e.g., residents of the European Union,) specifying additional polices may be required.
This type is also used to override the shipping costs of one or more shipping service options that are associated with the fulfillment policy, to enable eBay Plus eligibility for a listing, or to enable the Best Offer feature on the listing."
- },
- "Location": {
- "type": "object",
- "properties": {
- "address": {
- "description": "The address container is always returned in getInventoryLocation/getInventoryLocations calls. Except in the case of a store or fulfillment center location, a full address is not a requirement when setting up an inventory location.",
- "$ref": "#/components/schemas/Address"
- },
- "geoCoordinates": {
- "description": "This container displays the Global Positioning System (GPS) latitude and longitude coordinates for the inventory location.
This container is only returned if the geo-coordinates are set for an inventory location.",
- "$ref": "#/components/schemas/GeoCoordinates"
- },
- "locationId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for the location.
Note: This field should not be confused with the seller-defined merchantLocationKey value. It is the merchantLocationKey value which is used to identify an inventory location when working with inventory location API calls. The locationId value is only used internally by eBay."
- }
- },
- "description": "A complex type that is used to provide the physical address of a location, and it geo-coordinates."
- },
- "LocationAvailabilityDetails": {
- "type": "object",
- "properties": {
- "merchantLocationKey": {
- "type": "string",
- "description": "The unique identifier of a sellerās fulfillment center location where inventory is available for the item or item variation.
Note: When creating a location mapping using the createOrReplaceSkuLocationMapping method, the value entered in this field must be associated with a location with the FULFILLMENT_CENTER location type, or an error will occur. Sellers can check the locationTypes array in the response of the getInventoryLocations method to see if their location has a value of FULFILLMENT_CENTER."
- }
- },
- "description": "This type provides the unique identifier of an inventory location that is associated with a SKU within a listing."
- },
- "LocationDetails": {
- "type": "object",
- "properties": {
- "address": {
- "description": "This required container sets the physical address of an inventory location. Except in the case store or fulfillment center location, a full address is not a requirement when setting up a location. For warehouse locations, the fields required in this container are either of the following sets:- city, stateOrProvince, and country
- postalCode and country
",
- "$ref": "#/components/schemas/Address"
- },
- "geoCoordinates": {
- "description": "This container is used to set the Global Positioning System (GPS) latitude and longitude coordinates for the inventory location.
Geographical coordinates are required for the location of In-Store Pickup inventory. ",
- "$ref": "#/components/schemas/GeoCoordinates"
- }
- },
- "description": "This type is used by the createInventoryLocation call to provide an full or partial address of an inventory location."
- },
- "LocationMapping": {
- "type": "object",
- "properties": {
- "locations": {
- "type": "array",
- "description": "This array represents a collection of fulfillment center locations mapped to a SKU.
Note: Only the first 50 locations mapped to a SKU will be considered when calculating estimated delivery dates. Sellers can set up more than 50 locations using this method, but only the first 50 locations will be considered for calculating the estimates.",
- "items": {
- "$ref": "#/components/schemas/LocationAvailabilityDetails"
- }
- }
- },
- "description": "This type provides an array of locations that are associated with a SKU within a listing."
- },
- "LocationResponse": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the current page of results from the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The number of items returned on a single page from the result set.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value is set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
- },
- "total": {
- "type": "integer",
- "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
- "format": "int32"
- },
- "locations": {
- "type": "array",
- "description": "An array of one or more of the merchant's inventory locations.",
- "items": {
- "$ref": "#/components/schemas/InventoryLocationResponse"
- }
- }
- },
- "description": "This type is used by the base response payload for the getInventoryLocations call."
- },
- "Manufacturer": {
- "type": "object",
- "properties": {
- "addressLine1": {
- "type": "string",
- "description": "The first line of the product manufacturer's street address.
Max length: 180 characters"
- },
- "addressLine2": {
- "type": "string",
- "description": "The second line of the product manufacturer's street address. This field is not always used, but can be used for secondary address information such as 'Suite Number' or 'Apt Number'.
Max length: 180 characters"
- },
- "city": {
- "type": "string",
- "description": "The city of the product manufacturer's street address.
Max length: 64 characters"
- },
- "companyName": {
- "type": "string",
- "description": "The company name of the the product manufacturer.
Max length: 100 characters"
- },
- "country": {
- "type": "string",
- "description": "This defines the list of valid country codes, adapted from http://www.iso.org/iso/country_codes, ISO 3166-1 country code. List elements take the following form to identify a two-letter code with a short name in English, a three-digit code, and a three-letter code: For example, the entry for Japan includes Japan, 392, JPN. Short codes provide uniform recognition, avoiding language-dependent country names. The number code is helpful where Latin script may be problematic. Not all listed codes are universally recognized as countries, for example: code AQ is Antarctica, 010, ATA For implementation help, refer to eBay API documentation"
- },
- "email": {
- "type": "string",
- "description": "The product manufacturer's business email address.
Max length: 180 characters"
- },
- "phone": {
- "type": "string",
- "description": "The product manufacturer's business phone number.
Max length: 64 characters"
- },
- "postalCode": {
- "type": "string",
- "description": "The postal code of the product manufacturer's street address.
Max length: 9 characters"
- },
- "stateOrProvince": {
- "type": "string",
- "description": "The state or province of the product manufacturer's street address.
Max length: 64 characters"
- }
- },
- "description": "This type provides name and contact information about the manufacturer of the item."
- },
- "MigrateListing": {
- "type": "object",
- "properties": {
- "listingId": {
- "type": "string",
- "description": "The unique identifier of the eBay listing to migrate to the new Inventory model. In the Trading API, this field is known as the ItemID.
Up to five unique eBay listings may be specified here in separate listingId fields. The seller should make sure that each of these listings meet the requirements that are stated at the top of this Call Reference page."
- }
- },
- "description": "This type is used to specify one to five eBay listings that will be migrated to the new Inventory model."
- },
- "MigrateListingResponse": {
- "type": "object",
- "properties": {
- "errors": {
- "type": "array",
- "description": "If one or more errors occur with the attempt to migrate the listing, this container will be returned with detailed information on each error.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "inventoryItemGroupKey": {
- "type": "string",
- "description": "This field will only be returned for a multiple-variation listing that the seller attempted to migrate. Its value is auto-generated by eBay. For a multiple-variation listing that is successfully migrated to the new Inventory model, eBay automatically creates an inventory item group object for the listing, and the seller will be able to retrieve and manage that new inventory item group object by using the value in this field."
- },
- "inventoryItems": {
- "type": "array",
- "description": "This container exists of an array of SKU values and offer IDs. For single-variation listings, this will only be one SKU value and one offer ID (if listing was successfully migrated), but multiple SKU values and offer IDs will be returned for multiple-variation listings.",
- "items": {
- "$ref": "#/components/schemas/InventoryItemListing"
- }
- },
- "listingId": {
- "type": "string",
- "description": "The unique identifier of the eBay listing that the seller attempted to migrate."
- },
- "marketplaceId": {
- "type": "string",
- "description": "This is the unique identifier of the eBay Marketplace where the listing resides. The value fo the eBay US site will be EBAY_US. For implementation help, refer to eBay API documentation"
- },
- "statusCode": {
- "type": "integer",
- "description": "This field is returned for each listing that the seller attempted to migrate. See the HTTP status codes table to see which each status code indicates.",
- "format": "int32"
- },
- "warnings": {
- "type": "array",
- "description": "If one or more warnings occur with the attempt to migrate the listing, this container will be returned with detailed information on each warning. It is possible that a listing can be successfully migrated even if a warning occurs.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type is used to display the results of each listing that the seller attempted to migrate."
- },
- "NameValueList": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "This string value identifies the motor vehicle aspect, such as 'make', 'model', 'year', 'trim', and 'engine'. Typically, the make, model, and year of the motor vehicle are always required, with the trim and engine being necessary sometimes, but it will be dependent on the part or accessory, and on the vehicle class.
The getCompatibilityProperties method of the Taxonomy API can be used to retrieve applicable vehicle aspect names for a specified category."
- },
- "value": {
- "type": "string",
- "description": "This string value identifies the motor vehicle aspect specified in the corresponding name field. For example, if the name field is 'make', this field may be 'Toyota', or if the name field is 'model', this field may be 'Camry'.
The getCompatibilityPropertyValues method of the Taxonomy API can be used to retrieve possible values for vehicle aspect names."
- }
- },
- "description": "This type is used by the compatibilityProperties container to identify a motor vehicle using name/value pairs."
- },
- "OfferKeyWithId": {
- "type": "object",
- "properties": {
- "offerId": {
- "type": "string",
- "description": "The unique identifier of an unpublished offer for which expected listing fees will be retrieved. One to 250 offerId values can be passed in to the offers container for one getListingFees call.
Use the getOffers method to retrieve offer IDs.
Note: Errors will occur if offerId values representing published offers are passed in."
- }
- },
- "description": "This type is used by the getListingFees call to indicate the unpublished offer(s) for which expected listing fees will be retrieved. The user passes in one or more offerId values (a maximum of 250). See the Standard selling fees help page for more information on listing fees."
- },
- "OfferKeysWithId": {
- "type": "object",
- "properties": {
- "offers": {
- "type": "array",
- "description": "This container is used to identify one or more (up to 250) unpublished offers for which expected listing fees will be retrieved. The user passes one or more offerId values (maximum of 250) in to this container to identify the unpublished offers in which to retrieve expected listing fees. This call is only applicable for offers in the unpublished state.
The call response gives aggregate fee amounts per eBay marketplace, and does not give fee information at the individual offer level.",
- "items": {
- "$ref": "#/components/schemas/OfferKeyWithId"
- }
- }
- },
- "description": "This type is used by the base request payload of the getListingFees call."
- },
- "OfferPriceQuantity": {
- "type": "object",
- "properties": {
- "availableQuantity": {
- "type": "integer",
- "description": "This field is used if the seller wants to modify the current quantity of the inventory item that will be available for purchase in the offer (identified by the corresponding offerId value). Either the availableQuantity field or the price container is required, but not necessarily both.",
- "format": "int32"
- },
- "offerId": {
- "type": "string",
- "description": "This field is the unique identifier of the offer. If an offers container is used to update one or more offers associated to a specific inventory item, the offerId value is required in order to identify the offer to update with a modified price and/or quantity.
The seller can use the getOffers method (passing in the correct SKU value as a query parameter) to retrieve offerId values for offers associated with the SKU."
- },
- "price": {
- "description": "This container is used if the seller wants to modify the current price of the inventory item. The dollar value set here will be the new price of the inventory item in the offer (identified by the corresponding offerId value). Either the availableQuantity field or the price container is required, but not necessarily both.",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type is used by the offers container in a Bulk Update Price and Quantity call to update the current price and/or quantity of one or more offers associated with a specific inventory item."
- },
- "OfferResponse": {
- "type": "object",
- "properties": {
- "offerId": {
- "type": "string",
- "description": "The unique identifier of the offer that was just created with a createOffer call. It is not returned if the createOffer call fails to create an offer. This identifier will be needed for many offer-related calls. Note: The offerId value is only returned with a successful createOffer call. This field will not be returned in the updateOffer response.
"
- },
- "warnings": {
- "type": "array",
- "description": "This container will contain an array of errors and/or warnings when a call is made, and errors and/or warnings occur.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type is used by the response payload of the createOffer and updateOffer calls. The offerId field contains the unique identifier for the offer if the offer is successfully created by the createOffer call. The warnings field contains any errors and/or warnings that may have been triggered by the call. Note: The offerId value is only returned with a successful createOffer call. This field will not be returned in the updateOffer response.
"
- },
- "OfferResponseWithListingId": {
- "type": "object",
- "properties": {
- "errors": {
- "type": "array",
- "description": "This container will be returned if there were one or more errors associated with publishing the offer.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "listingId": {
- "type": "string",
- "description": "The unique identifier of the newly-created eBay listing. This field is only returned if the seller successfully published the offer and created the new eBay listing."
- },
- "offerId": {
- "type": "string",
- "description": "The unique identifier of the offer that the seller published (or attempted to publish)."
- },
- "statusCode": {
- "type": "integer",
- "description": "The HTTP status code returned in this field indicates the success or failure of publishing the offer specified in the offerId field. See the HTTP status codes table to see which each status code indicates.",
- "format": "int32"
- },
- "warnings": {
- "type": "array",
- "description": "This container will be returned if there were one or more warnings associated with publishing the offer.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type is used to indicate the status of each offer that the user attempted to publish. If an offer is successfully published, an eBay listing ID (also known as an Item ID) is returned. If there is an issue publishing the offer and creating the new eBay listing, the information about why the listing failed should be returned in the errors and/or warnings containers."
- },
- "OfferSkuResponse": {
- "type": "object",
- "properties": {
- "errors": {
- "type": "array",
- "description": "This container will be returned at the offer level, and will contain one or more errors if any occurred with the attempted creation of the corresponding offer.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "format": {
- "type": "string",
- "description": "This enumeration value indicates the listing format of the offer. For implementation help, refer to eBay API documentation"
- },
- "marketplaceId": {
- "type": "string",
- "description": "This enumeration value is the unique identifier of the eBay marketplace for which the offer will be made available. This enumeration value should be the same for all offers since the bulkCreateOffer method can only be used to create offers for one eBay marketplace at a time. For implementation help, refer to eBay API documentation"
- },
- "offerId": {
- "type": "string",
- "description": "The unique identifier of the newly-created offer. This identifier should be automatically created by eBay if the creation of the offer was successful. It is not returned if the creation of the offer was not successful. In which case, the user may want to scan the corresponding errors and/or warnings container to see what the issue may be."
- },
- "sku": {
- "type": "string",
- "description": "The seller-defined Stock-Keeping Unit (SKU) of the inventory item. The sku value is required for each product offer that the seller is trying to create, and it is always returned to identified the product that is associated with the offer."
- },
- "statusCode": {
- "type": "integer",
- "description": "The integer value returned in this field is the http status code. If an offer is created successfully, the value returned in this field should be 200. A user can view the HTTP status codes section for information on other status codes that may be returned with the bulkCreateOffer method.",
- "format": "int32"
- },
- "warnings": {
- "type": "array",
- "description": "This container will be returned at the offer level, and will contain one or more warnings if any occurred with the attempted creation of the corresponding offer. Note that it is possible that an offer can be created successfully even if one or more warnings are triggered.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type is used by the bulkCreateOffer response to show the status of each offer that the seller attempted to create with the bulkCreateOffer method. For each offer that is created successfully, the returned statusCode value should be 200, and a unique offerId should be created for each offer. If any issues occur with the creation of any offers, errors and/or warnings containers will be returned."
- },
- "Offers": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "This is the URL to the current page of offers."
- },
- "limit": {
- "type": "integer",
- "description": "This integer value is the number of offers that will be displayed on each results page.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "This is the URL to the next page of offers. This field will only be returned if there are additional offers to view."
- },
- "offers": {
- "type": "array",
- "description": "This container is an array of one or more of the seller's offers for the SKU value that is passed in through the required sku query parameter.
Note: Currently, the Inventory API does not support the same SKU across multiple eBay marketplaces.
Max Occurs: 25",
- "items": {
- "$ref": "#/components/schemas/EbayOfferDetailsWithAll"
- }
- },
- "prev": {
- "type": "string",
- "description": "This is the URL to the previous page of offers. This field will only be returned if there are previous offers to view."
- },
- "size": {
- "type": "integer",
- "description": "This integer value indicates the number of offers being displayed on the current page of results. This number will generally be the same as the limit value if there are additional pages of results to view.
Note: The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, getOffers will return two offers and this value will be 2. Otherwise, only one offer will be returned and this value will be 1.",
- "format": "int32"
- },
- "total": {
- "type": "integer",
- "description": "This integer value is the total number of offers that exist for the specified SKU value. Based on this number and on the limit value, the seller may have to toggle through multiple pages to view all offers.
Note: The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, getOffers will return two offers, so this value would be 2. Otherwise, only one offer will be returned and this value will be 1.",
- "format": "int32"
- }
- },
- "description": "This type is used by the base response of the getOffers call, and it is an array of one or more of the seller's offers, along with pagination data."
- },
- "OperatingHours": {
- "type": "object",
- "properties": {
- "dayOfWeekEnum": {
- "type": "string",
- "description": "A dayOfWeekEnum value is required for each day of the week that the store location has regular operating hours.
This field is returned if operating hours are defined for the store location. For implementation help, refer to eBay API documentation"
- },
- "intervals": {
- "type": "array",
- "description": "This container is used to define the opening and closing times of a store location's working day (defined in the dayOfWeekEnum field). An intervals container is needed for each day of the week that the store location is open. If a store location closes for lunch (or any other period during the day) and then reopens, multiple open and close pairs are needed
This container is returned if operating hours are defined for the store location.",
- "items": {
- "$ref": "#/components/schemas/Interval"
- }
- }
- },
- "description": "This type is used to express the regular operating hours of a merchant's store or fulfillment center during the days of the week."
- },
- "Overrides": {
- "type": "object",
- "properties": {
- "cutOffTime": {
- "type": "string",
- "description": "This field is used to override the cut-off time(s) specified in the weeklySchedule container. If an order is placed after this time in the specified date or date range, it will be handled by the seller on the following day.
Format: 00:00"
- },
- "endDate": {
- "type": "string",
- "description": "The end date of the cut-off time override in ISO 8601 format, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Note: If the cut-off time override is only for a single day, input the same date in the startDate and endDate fields.
Format: [YYYY]-[MM]-[DD]
Example: 2024-08-06
Note: The time zone for this date is specified from the timeZoneId field. If this field is not used, the time zone will be derived from the provided address."
- },
- "startDate": {
- "type": "string",
- "description": "The start date of the cut-off time override in ISO 8601 format, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Note: If the cut-off time override is only for a single day, input the same date in the startDate and endDate fields.
Format: [YYYY]-[MM]-[DD]
Example: 2024-08-04
Note: The time zone for this date is specified from the timeZoneId field. If this field is not used, the time zone will be derived from the provided address."
- }
- },
- "description": "This type defines the override dates for cut-off times. This allows sellers to set special hours for their inventory location and specify different cut-off times on these days."
- },
- "PackageWeightAndSize": {
- "type": "object",
- "properties": {
- "dimensions": {
- "description": "This container is used to indicate the length, width, and height of the shipping package that will be used to ship the inventory item. The dimensions of a shipping package are needed when calculated shipping is used.
This container will be returned if package dimensions are set for the inventory item.",
- "$ref": "#/components/schemas/Dimension"
- },
- "packageType": {
- "type": "string",
- "description": "This enumeration value indicates the type of shipping package used to ship the inventory item. The supported values for this field can be found in the PackageTypeEnum type.
This field will be returned if the package type is set for the inventory item.
Note: You can use the GeteBayDetails Trading API call to retrieve a list of supported package types for a specific marketplace. For implementation help, refer to eBay API documentation"
- },
- "shippingIrregular": {
- "type": "boolean",
- "description": "A value of true indicates that the package is irregular and cannot go through the stamping machine at the shipping service office. This field applies to calculated shipping only. Irregular packages require special or fragile handling."
- },
- "weight": {
- "description": "This container is used to specify the weight of the shipping package that will be used to ship the inventory item. The weight of a shipping package are needed when calculated shipping is used, or if flat-rate shipping rates are used, but with a weight surcharge.
This field will be returned if package weight is set for the inventory item.",
- "$ref": "#/components/schemas/Weight"
- }
- },
- "description": "This type is used to indicate the package type, weight, and dimensions of the shipping package. Package weight and dimensions are required when calculated shipping rates are used, and weight alone is required when flat-rate shipping is used, but with a weight surcharge. See the Calculated shipping help page for more information on calculated shipping."
- },
- "PickupAtLocationAvailability": {
- "type": "object",
- "properties": {
- "availabilityType": {
- "type": "string",
- "description": "The enumeration value in this field indicates the availability status of the inventory item at the merchant's physical store specified by the pickupAtLocationAvailability.merchantLocationKey field. This field is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.
See AvailabilityTypeEnum for more information about how/when you use each enumeration value. For implementation help, refer to eBay API documentation"
- },
- "fulfillmentTime": {
- "description": "This container is used to indicate how soon an In-Store Pickup order will be available for pickup by the buyer after the order takes place. This container is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.",
- "$ref": "#/components/schemas/TimeDuration"
- },
- "merchantLocationKey": {
- "type": "string",
- "description": "The unique identifier of a merchant's store where the In-Store Pickup inventory item is currently located, or where inventory will be sent to. If the merchant's store is currently awaiting for inventory, the availabilityType value should be SHIP_TO_STORE. This field is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.
Use the getInventoryLocations method to retrieve merchant location keys.
Max length: 36"
- },
- "quantity": {
- "type": "integer",
- "description": "This integer value indicates the quantity of the inventory item that is available for In-Store Pickup at the store identified by the merchantLocationKey value. The value of quantity should be an integer value greater than 0, unless the inventory item is out of stock. This field is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.",
- "format": "int32"
- }
- },
- "description": "This type is used to specify/indicate the quantity of the inventory item that is available for an In-Store Pickup order at the merchant's physical store (specified by the merchantLocationKey field)."
- },
- "PriceQuantity": {
- "type": "object",
- "properties": {
- "offers": {
- "type": "array",
- "description": "This container is needed if the seller is updating the price and/or quantity of one or more published offers, and a successful call will actually update the active eBay listing with the revised price and/or available quantity.
This call is not designed to work with unpublished offers. For unpublished offers, the seller should use the updateOffer call to update the available quantity and/or price.
If the seller is also using the shipToLocationAvailability container and sku field to update the total 'ship-to-home' quantity of the inventory item, the SKU value associated with the corresponding offerId value(s) must be the same as the corresponding sku value that is passed in, or an error will occur.
A separate (OfferPriceQuantity) node is required for each offer being updated.",
- "items": {
- "$ref": "#/components/schemas/OfferPriceQuantity"
- }
- },
- "shipToLocationAvailability": {
- "description": "This container is needed if the seller is updating the total 'ship-to-home' quantity for the corresponding inventory item (specified in the sku field). A successful call will update the inventory item record associated with the sku value.",
- "$ref": "#/components/schemas/ShipToLocationAvailability"
- },
- "sku": {
- "type": "string",
- "description": "This is the seller-defined SKU value of the inventory item whose total 'ship-to-home' quantity will be updated. This field is only required when the seller is updating the total quantity of an inventory item using the shipToLocationAvailability container. If the seller is updating the price and/or quantity of one or more specific offers, one or more offerId values are used instead, and the sku value is not needed.
If the seller wants to update the price and/or quantity of one or more offers, and also wants to update the total 'ship-to-home' quantity of the corresponding inventory item, the SKU value associated with the offerId value(s) must be the same as the corresponding sku value that is passed in, or an error will occur.
Use the getInventoryItems method to retrieve SKU values.
Max Length: 50
"
- }
- },
- "description": "This type is used to update the total \"ship-to-home\" quantity for one or more inventory items and/or to update the price and/or quantity of one or more specific offers associated with one or more inventory items."
- },
- "PriceQuantityResponse": {
- "type": "object",
- "properties": {
- "errors": {
- "type": "array",
- "description": "This array will be returned if there were one or more errors associated with the update to the offer or inventory item record.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "offerId": {
- "type": "string",
- "description": "The unique identifier of the offer that was updated. This field will not be returned in situations where the seller is only updating the total 'ship-to-home' quantity of an inventory item record."
- },
- "sku": {
- "type": "string",
- "description": "This is the seller-defined SKU value of the product. This field is returned whether the seller attempted to update an offer with the SKU value or just attempted to update the total 'ship-to-home' quantity of an inventory item record.
Max Length: 50
"
- },
- "statusCode": {
- "type": "integer",
- "description": "The value returned in this container will indicate the status of the attempt to update the price and/or quantity of the offer (specified in the corresponding offerId field) or the attempt to update the total 'ship-to-home' quantity of an inventory item (specified in the corresponding sku field). For a completely successful update of an offer or inventory item record, a value of 200 will appear in this field. A user can view the HTTP status codes section for information on other status codes that may be returned with the bulkUpdatePriceQuantity method.",
- "format": "int32"
- },
- "warnings": {
- "type": "array",
- "description": "This array will be returned if there were one or more warnings associated with the update to the offer or inventory item record.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type is used to display the result for each offer and/or inventory item that the seller attempted to update with a bulkUpdatePriceQuantity call. If any errors or warnings occur, the error/warning data is returned at the offer/inventory item level."
- },
- "PricingSummary": {
- "type": "object",
- "properties": {
- "auctionReservePrice": {
- "description": "This field indicates the lowest price at which the seller is willing to sell an item through an auction listing. Note that setting a Reserve Price will incur a listing fee of $5 or 7.5% of the Reserve Price, whichever is greater. The minimum fee is $5.
Important: This fee is charged regardless of whether or not the item is sold.",
- "$ref": "#/components/schemas/Amount"
- },
- "auctionStartPrice": {
- "description": "This field indicates the minimum bidding price for the auction. The bidding starts at this price.
Note: If the auctionReservePrice is also specified, the value of auctionStartPrice must be lower than the value of auctionReservePrice.",
- "$ref": "#/components/schemas/Amount"
- },
- "minimumAdvertisedPrice": {
- "description": "This container is needed if the Minimum Advertised Price (MAP) feature will be used in the offer. Minimum Advertised Price (MAP) is an agreement between suppliers (or manufacturers (OEM)) and the retailers (sellers) stipulating the lowest price an item is allowed to be advertised at. Sellers can only offer prices below this price through the use of other discounts. The MAP feature is only available to eligible US sellers. This field will be ignored if the seller and or the listing is not eligible for the MAP feature.
This container will be returned by getOffer and getOffers if set for the offer.",
- "$ref": "#/components/schemas/Amount"
- },
- "originallySoldForRetailPriceOn": {
- "type": "string",
- "description": "This field is needed if the Strikethrough Pricing (STP) feature will be used in the offer. This field indicates that the product was sold for the price in the originalRetailPrice field on an eBay site, or sold for that price by a third-party retailer. When using the createOffer or updateOffer calls, the seller will pass in a value of ON_EBAY to indicate that the product was sold for the originalRetailPrice on an eBay site, or the seller will pass in a value of OFF_EBAY to indicate that the product was sold for the originalRetailPrice through a third-party retailer. This field and the originalRetailPrice field are only applicable if the seller and listing are eligible to use the Strikethrough Pricing feature, a feature which is limited to the US (core site and Motors), UK, Germany, Canada (English and French versions), France, Italy, and Spain sites.
This field will be returned by getOffer and getOffers if set for the offer. For implementation help, refer to eBay API documentation"
- },
- "originalRetailPrice": {
- "description": "This container is needed if the Strikethrough Pricing (STP) feature will be used in the offer. The dollar value passed into this field indicates the original retail price set by the manufacturer (OEM). eBay does not maintain or validate the value supplied here by the seller. The dollar value in this field should always be more than the dollar value in the price container. This field and the originallySoldForRetailPriceOn field are only applicable if the seller and listing are eligible to use the Strikethrough Pricing feature, a feature which is limited to the US (core site and Motors), UK, Germany, Canada (English and French versions), France, Italy, and Spain sites. Compare the originalRetailPrice and the dollar value in the price field to determine the amount of savings to the buyer. This Original Retail Price will have a strikethrough line through for a marketing affect.
This container will be returned by getOffer and getOffers if set for the offer.",
- "$ref": "#/components/schemas/Amount"
- },
- "price": {
- "description": "This is the listing price of the product. A listing price must be specified before publishing an offer, but it is possible to create an offer without a price.
For published offers, this container will always be returned, but for unpublished offers, this container will only be returned if set for the offer.
Important!Publish offer note: This container and its two child fields (currency and value) are required before an offer can be published to create an active listing.
PRE_CHECKOUT. To show the MAP price after the buyer already commits to buy the item, the seller will set this value to DURING_CHECKOUT. This field will be ignored if the seller and/or the listing is not eligible for the MAP feature.
This field will be returned by getOffer and getOffers if set for the offer. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used to specify the listing price for the product and settings for the Minimum Advertised Price and Strikethrough Pricing features. The price field must be supplied before an offer is published, but a seller may create an offer without supplying a price initially. The Minimum Advertised Price feature is only available on the US site. Strikethrough Pricing is available on the US, eBay Motors, UK, Germany, Canada (English and French), France, Italy, and Spain sites."
- },
- "Product": {
- "type": "object",
- "properties": {
- "aspects": {
- "type": "string",
- "description": "This is a collection of item specifics (aka product aspects) name-value pairs that provide more information about the product and might make it easier for buyers to find. To view required/recommended product aspects/item specifics names (and corresponding values) for a specific eBay category, sellers can use the getItemAspectsForCategory method of the Taxonomy API. Alternatively, sellers can view similar items on eBay.com in the same category to get an idea of what other sellers are using for product aspects/item specifics.
Sellers also have the option of specifying an eBay Product ID (ePID) or optionally, a Global Trade Item Number (GTIN) through the corresponding fields in the product container in an attempt to find a product match in the eBay Catalog. If a match is found based on the ePID or GTIN value, the product aspects that are defined for the eBay Catalog product will automatically get picked up by the newly created/updated inventory item.
Below is an example of the proper JSON syntax to use when manually inputting item specifics. Note that one item specific name, such as 'Features', can have more than one value. If an item specific name has more than one value, each value is delimited with a comma.
\"aspects\": {
\"Brand\": [\"GoPro\"],
\"Storage Type\": [\"Removable\"]
}
Note that inventory items that will become part of an inventory item group and multiple-variation listing should have the same attributes that are defined for the inventory item group.
This container will be returned if one or more item specific pairs are defined for the inventory item.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length for Aspect Name: 40
Max Length for Aspect Value: 50"
- },
- "brand": {
- "type": "string",
- "description": "The brand of the product. This field is often paired with the mpn field to identify a specific product by Manufacturer Part Number. This field is conditionally required if the eBay category requires a Manufacturer Part Number (MPN) value. If eBay is able to find a product match in the eBay Catalog when an eBay Product ID (ePID) or GTIN value (UPC, ISBN, or EAN) is supplied, all product details of that eBay Catalog product is picked up by the inventory item record (including brand) if the createOrReplaceInventoryItem call is successful.
This field is returned if defined for an inventory item. If a brand was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the brand field.
Max Length: 65"
- },
- "description": {
- "type": "string",
- "description": "The description of the product. The description of an existing inventory item can be added or modified with a createOrReplaceInventoryItem call. The description of an inventory item is automatically populated if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog.
Note that this field is optional but recommended. If a listingDescription field is omitted when creating and publishing a single-variation offer, the text in this field will be used instead. If neither the product.description field for the inventory item nor the listingDescription field for the offer exist, the publishOffer call will fail. If the inventory item will be part of an inventory item group/multiple-variation listing, this field should definitely be used to specify how the corresponding product variation is different (e.g. This is the green, extra-large version of the shirt). However, in the case of an inventory item group, the text in the description field of the inventory item group will become the listing description of the actual eBay listing instead of the text in this field.
Basic HTML tags are supported, including the following tags:- <b>
- <strong>
- <br>
- <ol>
- <ul>
- <li>
- Table tags including <table>, <tr>, <td>, <th>, <thead>, <tfoot>, <tbody>, <caption>, <colgroup>, and <col>
A seller can not use any active content in their listing description. Active content includes animation or video via JavaScript, Flash, plug-ins, or form actions.
This field is returned if defined for an inventory item. If one of the GTIN types (e.g. UPC) was passed in when the inventory item was created/modified and a product match was found in the eBay catalog, product description is one of the details that gets picked up from the catalog product.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length: 4000"
- },
- "ean": {
- "type": "array",
- "description": "The European Article Number/International Article Number (EAN) for the product. Although an ePID value is preferred when trying to find a product match in the eBay Catalog, this field can also be used in an attempt to find a product match in the eBay Catalog. If a product match is found in the eBay Catalog, the inventory item is automatically populated with available product details such as a title, a product description, product aspects (including the specified EAN value), and a link to any stock image that exists for the catalog product.
This field is returned if defined for an inventory item. If an EAN was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the ean field.",
- "items": {
- "type": "string"
- }
- },
- "epid": {
- "type": "string",
- "description": "The eBay Product Identifier (ePID) for the product. This field can be used to directly identify an eBay Catalog product. Based on its specified ePID value, eBay will search for the product in the eBay Catalog, and if a match is found, the inventory item is automatically populated with available product details such as product title, product description, product aspects, and a link to any stock image that exists for the catalog product.
In an attempt to find a eBay Catalog product match, an ePID value is always preferred over the other product identifiers, since it is possible that one GTIN value can be associated with multiple eBay Catalog products, and if multiple products are found, product details will not be picked up by the Inventory Item object.
Note: When listing in categoryID 173651 (Auto Performance Tuning Devices & Software), the use of catalog products is required. For more information, see Tuning devices and software.
This field is returned if defined for an inventory item."
- },
- "imageUrls": {
- "type": "array",
- "description": "An array of one or more links to images for the product. URLs must use the \"HTTPS\" protocol. Images can be self-hosted by the seller, or sellers can use the UploadSiteHostedPictures call of the Trading API to upload images to an eBay Picture Server. If successful, the response of the UploadSiteHostedPictures call will contain a full URL to the image on an eBay Picture Server. This is the URL that will be passed in through the imageUrls array. Before an offer can be published, at least one image must exist for the inventory item. In almost any category at no cost, sellers can include up to 24 pictures in one listing. For inventory items that are a part of an inventory item group/multiple-variation listings, a maximum of 12 pictures may be used per inventory item in the group. Motor vehicle listings are an exception. The number of included pictures in motor vehicle listings depend on the selected vehicle package (see Fees for selling vehicles on eBay Motors).
A link to a stock image for a product may automatically be populated for an inventory item if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog.
This container will always be returned for an inventory item that is part of a published offer since a published offer will always have at least one picture, but this container will only be returned if defined for inventory items that are not a part of a published offer.
Important!Publish offer note: This array is required and at least one image URL must be specified before an offer can be published to create an active listing.
This field is returned if defined for an inventory item. If an ISBN was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the isbn field.",
- "items": {
- "type": "string"
- }
- },
- "mpn": {
- "type": "string",
- "description": "The Manufacturer Part Number (MPN) of a product. This field is paired with the brand field to identify a product. Some eBay categories require MPN values. The getItemAspectsForCategory method in the Taxonomy API can be used to see if a category requires an MPN. The MPN value for a product may automatically be populated for an inventory item if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog.
This field is returned if defined for an inventory item. If an MPN was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the mpn field.
Max Length: 65"
- },
- "subtitle": {
- "type": "string",
- "description": "A subtitle is an optional listing feature that allows the seller to provide more information about the product, possibly including keywords that may assist with search results. An additional listing fee will be charged to the seller if a subtitle is used. For more information on using listing subtitles on the US site, see the Adding a subtitle to your listings help page. The subtitle of an existing inventory item can added, modified, or removed with a createOrReplaceInventoryItem call.
Note that the same subtitle text should be used for each inventory item that will be part of an inventory item group, and ultimately become one product variation within a multiple-variation listing.
This field will only be returned if set for an inventory item.
Max Length: 55"
- },
- "title": {
- "type": "string",
- "description": "The title of an inventory item can be added or modified with a createOrReplaceInventoryItem call. Although not immediately required, a title will be needed before an offer with the inventory item is published. The title of an inventory item is automatically populated if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog. If the inventory item will become part of a single-variation offer, and the listing is not a product-based listing, the text in this field will become the actual listing title for the published offer. However, if the inventory item will become part of a multiple-variation offer, the text in title field of the inventory item group entity will actually become the listing title for the published offer instead, although a title can still be provided for the inventory item, and it will actually become the title of the variation.
This field will always be returned for an inventory item that is part of a published offer since a published offer will always have a listing title, but this field will only be returned if defined for inventory items that are not a part of a published offer.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length: 80"
- },
- "upc": {
- "type": "array",
- "description": "The Universal Product Code (UPC) value for the product. Although an ePID value is preferred when trying to find a product match in the eBay Catalog, this field can also be used in an attempt to find a product match in the eBay Catalog. If a product match is found in the eBay Catalog, the inventory item is automatically populated with available product details such as a title, a product description, product aspects (including the specified UPC value), and a link to any stock image that exists for the catalog product.
This field is returned if defined for an inventory item. If a UPC was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the upc field.",
- "items": {
- "type": "string"
- }
- },
- "videoIds": {
- "type": "array",
- "description": "An array of one or more videoId values for the product. A video ID is a unique identifier that is automatically created by eBay when a seller successfully uploads a video to eBay using the uploadVideo method of the Media API.
For information on supported marketplaces and platforms, as well as other requirements and limitations of video support, please refer to Managing videos.
Note: Only one video per listing is supported.",
- "items": {
- "type": "string"
- }
- }
- },
- "description": "This type is used to define the product details, such as a title, a product description, product aspects/item specifics, and links to images for the product. Optionally, in a createOrReplaceInventoryItem call, a seller can pass in an eBay Product Identifier (ePID) or a Global Trade Item Number (GTIN) value, such as an EAN, an ISBN, a UPC, to identify a product to be matched with a product in the eBay Catalog. The information in this type is also returned in the getInventoryItem, getInventoryItems, and bulkGetInventoryItem calls if defined."
- },
- "ProductFamilyProperties": {
- "type": "object",
- "properties": {
- "engine": {
- "type": "string",
- "description": "Important! The productFamilyProperties container is no longer supported.
Important! The productFamilyProperties container is no longer supported.
Important! The productFamilyProperties container is no longer supported.
Important! The productFamilyProperties container is no longer supported.
Important! The productFamilyProperties container is no longer supported.
Note: This field is for future use."
- },
- "ktype": {
- "type": "string",
- "description": "This field can be used if the seller knows the K Type Number for the motor vehicle that is to be added to the compatible product list. If this K Type value is found in the eBay product catalog, the motor vehicle properties (e.g. make, model, year, engine, and trim) will automatically get picked up for that motor vehicle.
Only the AU, DE, ES, FR, IT, and UK marketplaces support the use of K Type Numbers."
- }
- },
- "description": "This type is used to identify a motor vehicle that is compatible with the corresponding inventory item (the SKU that is passed in as part of the call URI). The motor vehicle can be identified through an eBay Product ID or a K-Type value. The gtin field (for inputting Global Trade Item Numbers) is for future use only. If a motor vehicle is found in the eBay product catalog, the motor vehicle properties (engine, make, model, trim, and year) will automatically get picked up for that motor vehicle.
Note: Currently, parts compatibility is only applicable for motor vehicles, but it is possible that the Product Compatibility feature is expanded to other (non-vehicle) products in the future."
- },
- "ProductSafety": {
- "type": "object",
- "properties": {
- "component": {
- "type": "string",
- "description": "This field is used by the seller to provide product safety component information for the listing. For example, component information can include specific warnings related to product safety, such as 'Tipping hazard'.
Note: Component information can only be specified if used with the pictograms and/or statements field; if the component is provided without one or both of these fields, an error will occur.
Max length: 120 characters"
- },
- "pictograms": {
- "type": "array",
- "description": "An array of comma-separated string values used to provide product safety pictogram(s) for the listing.
If your product shows universal product safety or compliance symbols, please select the values corresponding to the product safety pictograms for display in the product safety section of the listing. The seller specifies the identifier of each pictogram in this field.
Note: For product safety pictograms, use the getProductSafetyLabels method of the Metadata API to find supported values for a specific marketplace/site.
A maximum of 2 pictograms are allowed for product safety.",
- "items": {
- "type": "string"
- }
- },
- "statements": {
- "type": "array",
- "description": "An array of comma-separated string values used to provide product safety statement(s) for the listing.
If your product shows universal product safety or compliance warnings, please select the values corresponding to the product safety statements for display in the product safety section of the listing. The seller specifies the identifier of each statement in this field.
Note: For product safety statements, use the getProductSafetyLabels method of the Metadata API to find supported values for a specific marketplace/site.
A maximum of 8 statements are allowed for product safety.",
- "items": {
- "type": "string"
- }
- }
- },
- "description": "This type is used to define the pictograms and statement containers, and the optional component field, that provide product safety and compliance related information."
- },
- "PublishByInventoryItemGroupRequest": {
- "type": "object",
- "properties": {
- "inventoryItemGroupKey": {
- "type": "string",
- "description": "This is the unique identifier of the inventory item group. All unpublished offers associated with this inventory item group will be published as a multiple-variation listing if the publishByInventoryItemGroup call is successful. The inventoryItemGroupKey identifier is automatically generated by eBay once an inventory item group is created.
To retrieve an inventoryItemGroupKey value, you can use the getInventoryItem method to retrieve an inventory item that is known to be in the inventory item group to publish, and then look for the inventory item group identifier under the groupIds container in the response of that call."
- },
- "marketplaceId": {
- "type": "string",
- "description": "This is the unique identifier of the eBay site on which the multiple-variation listing will be published. The marketplaceId enumeration values are found in MarketplaceEnum. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used by the request payload of the publishByInventoryItemGroup call. The identifier of the inventory item group to publish and the eBay marketplace where the listing will be published is needed in the request payload."
- },
- "PublishResponse": {
- "type": "object",
- "properties": {
- "listingId": {
- "type": "string",
- "description": "The unique identifier of the newly created eBay listing. This field is returned if the single offer (if publishOffer call was used) or group of offers in an inventory item group (if publishOfferByInventoryItemGroup call was used) was successfully converted into an eBay listing."
- },
- "warnings": {
- "type": "array",
- "description": "This container will contain an array of errors and/or warnings if any occur when a publishOffer or publishOfferByInventoryItemGroup call is made.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type is used by the base response payload of the publishOffer and publishOfferByInventoryItemGroup calls."
- },
- "RegionalProductCompliancePolicies": {
- "type": "object",
- "properties": {
- "countryPolicies": {
- "type": "array",
- "description": "The array of country-specific product compliance policies to be used by an offer when it is published and converted to a listing.",
- "items": {
- "$ref": "#/components/schemas/CountryPolicy"
- }
- }
- },
- "description": "This type lists regional product compliance policies to be used by an offer when it is published and converted to a listing."
- },
- "RegionalTakeBackPolicies": {
- "type": "object",
- "properties": {
- "countryPolicies": {
- "type": "array",
- "description": "The array of country-specific take-back policies to be used by an offer when it is published and converted to a listing.",
- "items": {
- "$ref": "#/components/schemas/CountryPolicy"
- }
- }
- },
- "description": "This type lists regional take-back policies to be used by an offer when it is published and converted to a listing."
- },
- "Regulatory": {
- "type": "object",
- "properties": {
- "documents": {
- "type": "array",
- "description": "This container provides a collection of regulatory documents associated with the listing.
For information on removing one or more files from a listing using the updateOffer method, see Remove documents from listings. .
Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory document information in their eBay listings. For more information on GPSR, see General Product Safety Regulation (GPSR).",
- "items": {
- "$ref": "#/components/schemas/Document"
- }
- },
- "energyEfficiencyLabel": {
- "description": "This container provides information about the energy efficiency for certain durable goods.
Note: Sellers in the EU and UK can use this container to provide European energy efficiency (EEK) information for listings in the Tyres and Appliance categories. If no EEK information is specified through this container, it will be retrieved through a third party vendor. For more information, see Energy efficiency information.
Note: Energy efficiency information is not required for all categories. Use the getRegulatoryPolicies method of the Metadata API to return metadata on the eBay categories that recommend or require energy efficiency-related fields.",
- "$ref": "#/components/schemas/EnergyEfficiencyLabel"
- },
- "hazmat": {
- "description": "This container is used by the seller to provide hazardous material information for the listing.
The statements element is required to complete the Hazmat section of a listing.
The following elements are optional:- pictograms
- signalWord
- component
Note: Hazmat information is not required for all categories. Use the getRegulatoryPolicies method of the Metadata API to return metadata on the eBay categories that recommend or require Hazmat-related fields.",
- "$ref": "#/components/schemas/Hazmat"
- },
- "manufacturer": {
- "description": "This container provides information about the manufacturer of the item.
Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory manufacturer information in their eBay listings. Manufacturer information is not required for all categories. Use the getRegulatoryPolicies method of the Metadata API to return metadata on the eBay categories that recommend or require manufacturer-related fields. For more information on GPSR, see General Product Safety Regulation (GPSR).",
- "$ref": "#/components/schemas/Manufacturer"
- },
- "productSafety": {
- "description": "This container is used to provide product safety information for the listing. One of the following elements is required to complete the Product Safety section for a listing: pictograms or statements. The component element is optional.
Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory product safety information in their eBay listings. Product safety information is not required for all categories. Use the getRegulatoryPolicies method of the Metadata API to return metadata on the eBay categories that recommend or require product safety-related fields. For more information on GPSR, see General Product Safety Regulation (GPSR). ",
- "$ref": "#/components/schemas/ProductSafety"
- },
- "repairScore": {
- "type": "number",
- "description": "This field represents the repair index for the listing.
The repair index identifies the manufacturer's repair score for a product (i.e., how easy is it to repair the product.) This field is a floating point value between 0.0 (i.e., difficult to repair,) and 10.0 (i.e., easily repaired.)
Note: 0 should not be used as a default value, as it implies the product is not repairable.
The format for repairScore is limited to one decimal place. For example:7.9 and 0.0 are both valid scores5.645 and 2.10 are both invalid scores
Note: Repair score is not applicable to all categories. Use the getExtendedProducerResponsibilityPolicies method of the Metadata API to see where repair score is applicable."
- },
- "responsiblePersons": {
- "type": "array",
- "description": "This container provides information about the EU-based Responsible Persons or entities associated with the listing.
A maximum of 5 EU Responsible Persons are supported.
Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory Responsible Persons information in their eBay listings. For more information on GPSR, see General Product Safety Regulation (GPSR).",
- "items": {
- "$ref": "#/components/schemas/ResponsiblePerson"
- }
- }
- },
- "description": "Type defining regulatory information that the seller is required to disclose."
- },
- "ResponsiblePerson": {
- "type": "object",
- "properties": {
- "addressLine1": {
- "type": "string",
- "description": "The first line of the Responsible Person's street address.
Max length: 180 characters"
- },
- "addressLine2": {
- "type": "string",
- "description": "The second line of the Responsible Person's address. This field is not always used, but can be used for secondary address information such as 'Suite Number' or 'Apt Number'.
Max length: 180 characters"
- },
- "city": {
- "type": "string",
- "description": "The city of the Responsible Person's street address.
Max length: 64 characters"
- },
- "companyName": {
- "type": "string",
- "description": "The name of the the Responsible Person or entity.
Max length: 100 characters"
- },
- "country": {
- "type": "string",
- "description": "This defines the list of valid country codes, adapted from http://www.iso.org/iso/country_codes, ISO 3166-1 country code. List elements take the following form to identify a two-letter code with a short name in English, a three-digit code, and a three-letter code: For example, the entry for Japan includes Japan, 392, JPN. Short codes provide uniform recognition, avoiding language-dependent country names. The number code is helpful where Latin script may be problematic. Not all listed codes are universally recognized as countries, for example: code AQ is Antarctica, 010, ATA For implementation help, refer to eBay API documentation"
- },
- "email": {
- "type": "string",
- "description": "The Responsible Person's email address.
Max length: 180 characters"
- },
- "phone": {
- "type": "string",
- "description": "The Responsible Person's business phone number.
Max length: 64 characters"
- },
- "postalCode": {
- "type": "string",
- "description": "The postal code of the Responsible Person's street address.
Max length: 9 characters"
- },
- "stateOrProvince": {
- "type": "string",
- "description": "The state of province of the Responsible Person's street address.
Max length: 64 characters"
- },
- "types": {
- "type": "array",
- "description": "The type(s) associated with the Responsible Person or entity.
Note: Currently, the only supported value is EUResponsiblePerson. ",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- }
- },
- "description": "This type provides information, such as name and contact details, for an EU-based Responsible Person or entity, associated with the product."
- },
- "SameDayShippingCutOffTimes": {
- "type": "object",
- "properties": {
- "overrides": {
- "type": "array",
- "description": "This container can be used to override the existing cut-off time(s), specified in the weeklySchedule container, for a specific date or date range.",
- "items": {
- "$ref": "#/components/schemas/Overrides"
- }
- },
- "weeklySchedule": {
- "type": "array",
- "description": "This container is used to specify the weekly schedule for shipping and handling cut-off times. A cut-off time is required for each business day that the fulfillment center operates. Any orders made after the specified cutOffTime on the specified day(s) of the week will be handled on the next day.",
- "items": {
- "$ref": "#/components/schemas/WeeklySchedule"
- }
- }
- },
- "description": "This type is used by the createInventoryLocation call to specify cut-off time(s) for an inventory location, as well as any overrides for these times."
- },
- "ShipToLocationAvailability": {
- "type": "object",
- "properties": {
- "availabilityDistributions": {
- "type": "array",
- "description": "This container is used to set the available quantity of the inventory item at one or more warehouse locations.
This container will be returned if available quantity is set for one or more inventory locations.",
- "items": {
- "$ref": "#/components/schemas/AvailabilityDistribution"
- }
- },
- "quantity": {
- "type": "integer",
- "description": "This container is used to set the total 'ship-to-home' quantity of the inventory item that will be available for purchase through one or more published offers. This field is not immediately required, but 'ship-to-home' quantity must be set before an offer of the inventory item can be published.
If an existing inventory item is being updated, and the 'ship-to-home' quantity already exists for the inventory item record, this field should be included again, even if the value is not changing, or the available quantity data will be lost.
Note: The availableQuantity field if set in the offer overrides the quantity field set here. See the note in Offer fields for details. ",
- "format": "int32"
- }
- },
- "description": "This type is used to specify the total 'ship-to-home' quantity of the inventory item that will be available for purchase through one or more published offers."
- },
- "ShipToLocationAvailabilityWithAll": {
- "type": "object",
- "properties": {
- "allocationByFormat": {
- "description": "This container is used to specify the quantity of the inventory item that is available for purchase, allocated by the offer types.",
- "$ref": "#/components/schemas/FormatAllocation"
- },
- "availabilityDistributions": {
- "type": "array",
- "description": "This container is used to set the available quantity of the inventory item at one or more warehouse locations.
This container will be returned if the available quantity is set for one or more inventory locations.",
- "items": {
- "$ref": "#/components/schemas/AvailabilityDistribution"
- }
- },
- "quantity": {
- "type": "integer",
- "description": "Important! Publish offer note: Although this field is not required before an offer can be published to create an active listing, out of stock listings will result if this field is omitted or set to 0.
This field is used to set the total 'ship-to-home' quantity of the inventory item that will be available for purchase through one or more published offers. This field is not immediately required, but 'ship-to-home' quantity must be set before an offer of the inventory item can be published.
If an existing inventory item is being updated, and the 'ship-to-home' quantity already exists for the inventory item record, this field should be included again, even if the value is not changing, or the available quantity data will be lost.",
- "format": "int32"
- }
- },
- "description": "This type is used to specify the total 'ship-to-home' quantity of the inventory items that will be available for purchase through one or more published offers."
- },
- "ShippingCostOverride": {
- "type": "object",
- "properties": {
- "additionalShippingCost": {
- "description": "The dollar value passed into this field will override the additional shipping cost that is currently set for the applicable shipping service option. The \"Additional shipping cost\" is the cost to ship each additional identical product to the buyer using the corresponding shipping service. The shipping service option in the fulfillment policy to override is controlled by the shippingServiceType and priority values.
If using an updateOffer call, and this field is defined for the offer being updated, this field must be supplied again, even if its value is not changing.
This field is returned in the getOffer and getOffers calls if defined.",
- "$ref": "#/components/schemas/Amount"
- },
- "priority": {
- "type": "integer",
- "description": "The integer value input into this field, along with the shippingServiceType value, sets which domestic or international shipping service option in the fulfillment policy will be modified with updated shipping costs. Specifically, the shippingCostOverrides.shippingServiceType value in a createOffer or updateOffer call must match the shippingOptions.optionType value in a fulfillment listing policy, and the shippingCostOverrides.priority value in a createOffer or updateOffer call must match the shippingOptions.shippingServices.sortOrderId value in a fulfillment listing policy.
This field is always required when overriding the shipping costs of a shipping service option, and will be always be returned for each shipping service option whose costs are being overridden.",
- "format": "int32"
- },
- "shippingCost": {
- "description": "The dollar value passed into this field will override the shipping cost that is currently set for the applicable shipping service option. This value will be the cost to ship one item to the buyer using the corresponding shipping service. The shipping service option in the fulfillment policy to override is controlled by the shippingServiceType and priority values.
If using an updateOffer call, and this field is defined for the offer being updated, this field must be supplied again, even if its value is not changing.
This field is returned in the getOffer and getOffers calls if defined.",
- "$ref": "#/components/schemas/Amount"
- },
- "shippingServiceType": {
- "type": "string",
- "description": "This enumerated value indicates whether the shipping service specified in the priority field is a domestic or an international shipping service option. To override the shipping costs for a specific domestic shipping service in the fulfillment listing policy, this field should be set to DOMESTIC, and to override the shipping costs for each international shipping service, this field should be set to INTERNATIONAL. This value, along with priority value, sets which domestic or international shipping service option in the fulfillment policy that will be modified with updated shipping costs. Specifically, the shippingCostOverrides.shippingServiceType value in a createOffer or updateOffer call must match the shippingOptions.optionType value in a fulfillment listing policy, and the shippingCostOverrides.priority value in a createOffer or updateOffer call must match the shippingOptions.shippingServices.sortOrderId value in a fulfillment listing policy.
This field is always required when overriding the shipping costs of a shipping service option, and will be always be returned for each shipping service option whose costs are being overridden. For implementation help, refer to eBay API documentation"
- },
- "surcharge": {
- "description": " Note: DO NOT USE THIS FIELD. Shipping surcharges for shipping service options can no longer be set with fulfillment business policies. To set a shipping surcharge for a shipping service option, only the Shipping rate tables tool in My eBay can be used.
The dollar value passed into this field will override the shipping surcharge that is currently set for the applicable shipping service option. The shipping service option in the fulfillment policy to override is controlled by the shippingServiceType and priority values.
If using an updateOffer call, and this field is defined for the offer being updated, this field must be supplied again, even if its value is not changing.
This field is returned in the getOffer and getOffers calls if defined.",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type is used if the seller wants to override the shipping costs or surcharge associated with a specific domestic or international shipping service option defined in the fulfillment listing policy that is being applied toward the offer. The shipping-related costs that can be overridden include the shipping cost to ship one item, the shipping cost to ship each additional item (if multiple quantity are purchased), and the shipping surcharge applied to the shipping service option."
- },
- "SpecialHours": {
- "type": "object",
- "properties": {
- "date": {
- "type": "string",
- "description": "A date value is required for each specific date that the store location has special operating hours.
The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2018-08-04T07:09:00.000Z
This field is returned if set for the store location."
- },
- "intervals": {
- "type": "array",
- "description": "This container is used to define the opening and closing times of a store location on a specific date (defined in the date field). An intervals container is needed for each specific date that the store has special operating hours. These special operating hours on the specific date override the normal operating hours for the specific day of the week. If a store location closes for lunch (or any other period during the day) and then reopens, multiple open and close pairs are needed.
This container is returned if set for the store location.",
- "items": {
- "$ref": "#/components/schemas/Interval"
- }
- }
- },
- "description": "This type is used to express the special operating hours of a store location on a specific date. A specialHours container is needed when the store's opening hours on a specific date are different than the normal operating hours on that particular day of the week."
- },
- "Specification": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "This is the name of product variation aspect. Typically, for clothing, typical aspect names are \"Size\" and \"Color\". Product variation aspects are not required immediately upon creating an inventory item group, but these aspects will be required before a multiple-variation listing containing this inventory item group is published. For each product variation aspect that is specified through the specifications container, one name value is required and two or more variations of this aspect are required through the values array.
Note: Each member of the inventory item group should have these same aspect names specified through the product.aspects container when the inventory item is created with the createOrReplaceInventoryItem or bulkCreateOrReplaceInventoryItem call.
Important!Publish offer note: This field is required before an offer can be published to create an active listing.
Max Length: 40"
- },
- "values": {
- "type": "array",
- "description": "This is an array of values pertaining to the corresponding product variation aspect (specified in the name field). Below is a sample of how these values will appear under a specifications container:
\"specifications\": [{
\"name\": \"Size\",
\"values\": [\"Small\",
\"Medium\",
\"Large\"]
},
{
\"name\": \"Color\",
\"values\": [\"Blue\",
\"White\",
\"Red\"]
}]
Note: Each member of the inventory item group should have these same aspect names, and each individual inventory item should have each variation of the product aspect values specified through the product.aspects container when the inventory item is created with the createOrReplaceInventoryItem or bulkCreateOrReplaceInventoryItem call.
Important!Publish offer note: This array is required and at least one value that matches the corresponding aspect name must be specified.
Max Length: 50",
- "items": {
- "type": "string"
- }
- }
- },
- "description": "This type is used to specify product aspects for which variations within an inventory item group vary, and the order in which they appear in the listing. For example, t-shirts in an inventory item group may be available in multiple sizes and colors."
- },
- "Tax": {
- "type": "object",
- "properties": {
- "applyTax": {
- "type": "boolean",
- "description": "When set to true, the seller's account-level sales-tax table will be used to calculate sales tax for an order.
Note: Sales-tax tables are available only for the US and Canada marketplaces.
Important! In the US, eBay now calculates, collects, and remits sales tax to the proper taxing authorities in all 50 states and Washington, DC. Sellers can no longer specify sales-tax rates for these jurisdictions using a tax table.
However, sellers may continue to use a sales-tax table to set rates for the following US territories:
- American Samoa (AS)
- Guam (GU)
- Northern Mariana Islands (MP)
- Palau (PW)
- US Virgin Islands (VI)
For complete information about using sales-tax tables, refer to Establishing sales-tax tables.
Note that a seller can enable the use of a sales-tax table, but if a sales-tax rate is not specified for the buyer's tax jurisdiction, sales tax will not be applied to the order.
When a thirdPartyTaxCategory value is used, applyTax must also be set to true.
This field will be returned by getOffer and getOffers if set for the offer.
For additional information, refer to Taxes and import charges."
- },
- "thirdPartyTaxCategory": {
- "type": "string",
- "description": "The tax exception category code. If this field is used, sales tax will also apply to a service/fee, and not just the item price. This is to be used only by sellers who have opted into sales tax being calculated by a sales tax calculation vendor. If you are interested in becoming a tax calculation vendor partner with eBay, contact developer-relations@ebay.com. One supported value for this field is WASTE_RECYCLING_FEE. If this field is used, the applyTax field must also be used and set to true
This field will be returned by getOffer and getOffers if set for the offer."
- },
- "vatPercentage": {
- "type": "number",
- "description": "This value is the Value Add Tax (VAT) rate for the item, if any. When a VAT percentage is specified, the item's VAT information appears on the listing's View Item page. In addition, the seller can choose to print an invoice that includes the item's net price, VAT percent, VAT amount, and total price. Since VAT rates vary depending on the item and on the user's country of residence, a seller is responsible for entering the correct VAT rate; it is not calculated by eBay.
To use VAT, a seller must be a business seller with a VAT-ID registered with eBay, and must be listing the item on a VAT-enabled site. Max applicable length is 6 characters, including the decimal (e.g., 12.345). The scale is 3 decimal places. (If you pass in 12.3456, eBay may round up the value to 12.346).
This field will be returned by getOffer and getOffers if set for the offer."
- }
- },
- "description": "This type is used to enable the use of a sales-tax table, to pass in a tax exception category code, or to specify a VAT percentage.
Note: Sales-tax tables are available only for the US and Canada marketplaces."
- },
- "TimeDuration": {
- "type": "object",
- "properties": {
- "unit": {
- "type": "string",
- "description": "This enumeration value indicates the time unit used to specify the fulfillment time, such as BUSINESS_DAY. For implementation help, refer to eBay API documentation"
- },
- "value": {
- "type": "integer",
- "description": "The integer value in this field, along with the time unit in the unit field, will indicate the fulfillment time.
For standard orders that will be shipped, this value will indicate the expected fulfillment time if the inventory item is shipped from the inventory location. If the value of this field is 4, and the value of the unit field is BUSINESS_DAY, then the estimated delivery date after purchase is 4 business days.",
- "format": "int32"
- }
- },
- "description": "This type is used to indicate the fulfillment time for an In-Store Pickup order, or for an order than will be shipped to the buyer."
- },
- "VariesBy": {
- "type": "object",
- "properties": {
- "aspectsImageVariesBy": {
- "type": "array",
- "description": "This container is used if the seller wants to include multiple images to demonstrate how variations within a multiple-variation listing differ. In this string field, the seller will specify the product aspect where the variations of the inventory item group vary, such as color. If Color is specified in this field, Color must also be one of the specifications.name values, and all available colors must appear in the corresponding specifications.values array.
If the aspectsImageVariesBy container is used, links to images of each variation should be specified through the imageUrls container of the inventory item group, or the seller can choose to include those links to images in each inventory item record for the inventory items in the group.
Important!Publish offer note: This array is required and at least one aspect (such as Color) must be specified before an offer can be published to create an active listing.
If a product aspect is specified in the aspectsImageVariesBy container, this product aspect (along with all variations of that product aspect) must be included in the specifications container. Before offers related to the inventory item group are published, the product aspects and values specified through the specifications container should be in synch with the name-value pairs specified through the product.aspects containers of the inventory items contained in the group. For example, if Color and Size are in this specifications container, each inventory item of the group should also have Color and Size as aspect names in their inventory item records.
This container is always returned if one or more offers associated with the inventory item group have been published. For inventory item groups that have yet to have any published offers, this container is only returned if set.
Important!Publish offer note: This array is required and at least one aspect with the available variations must be specified.
Cut-off times default to the time zone of the specified address if the timeZoneId is not provided.
Note: If cut-off hours are not specified for a particular day, the fulfillment center is considered to be on holiday for that day.
Format: 00:00"
- },
- "dayOfWeekEnum": {
- "type": "array",
- "description": "This comma-separated array defines the days of week for which the specified cutOffTime is used.",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- }
- },
- "description": "This type describes the weekly schedule for cut-off times."
- },
- "Weight": {
- "type": "object",
- "properties": {
- "unit": {
- "type": "string",
- "description": "The unit of measurement used to specify the weight of a shipping package. Both the unit and value fields are required if the weight container is used. If the English system of measurement is being used, the applicable values for weight units are POUND and OUNCE. If the metric system of measurement is being used, the applicable values for weight units are KILOGRAM and GRAM. The metric system is used by most countries outside of the US. For implementation help, refer to eBay API documentation"
- },
- "value": {
- "type": "number",
- "description": "The actual weight (in the measurement unit specified in the unit field) of the shipping package. Both the unit and value fields are required if the weight container is used. If a shipping package weighed 20.5 ounces, the container would look as follows:
\"weight\": {
\"value\": 20.5,
\"unit\": \"OUNCE\"
}"
- }
- },
- "description": "This type is used to specify the weight (and the unit used to measure that weight) of a shipping package. The weight container is conditionally required if the seller will be offering calculated shipping rates to determine shipping cost, or is using flat-rate costs, but charging a weight surcharge. See the Calculated shipping help page for more information on calculated shipping."
- },
- "WithdrawByInventoryItemGroupRequest": {
- "type": "object",
- "properties": {
- "inventoryItemGroupKey": {
- "type": "string",
- "description": "This is the unique identifier of the inventory item group. This identifier is automatically generated by eBay once an inventory item group is created.
To retrieve an inventoryItemGroupKey value, you can use the getInventoryItem method to retrieve an inventory item that is known to be in the inventory item group to publish, and then look for the inventory item group identifier under the groupIds container in the response of that call."
- },
- "marketplaceId": {
- "type": "string",
- "description": "This is the unique identifier of the eBay site for which the offer will be made available. See MarketplaceEnum for supported values. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type is used by the base request of the WithdrawByInventoryItemGroup method, which is used to end a multiple-variation listing."
- },
- "WithdrawResponse": {
- "type": "object",
- "properties": {
- "listingId": {
- "type": "string",
- "description": "The unique identifier of the eBay listing associated with the offer that was withdrawn. This field will not be returned if the eBay listing was not successfully ended."
- },
- "warnings": {
- "type": "array",
- "description": "This container will be returned if there were one or more warnings associated with the attempt to withdraw the offer.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "The base response of the withdrawOffer call."
- }
- },
- "securitySchemes": {
- "api_auth": {
- "type": "oauth2",
- "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
- "flows": {
- "authorizationCode": {
- "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
- "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
- "scopes": {
- "https://api.ebay.com/oauth/api_scope/sell.inventory": "View and manage your inventory and offers",
- "https://api.ebay.com/oauth/api_scope/sell.inventory.readonly": "View your inventory and offers"
}
- }
}
- }
}
- }
}
\ No newline at end of file
diff --git a/specs/sell_logistics_v1_oas3.json b/specs/sell_logistics_v1_oas3.json
index f11dced1..dc0ae8bf 100644
--- a/specs/sell_logistics_v1_oas3.json
+++ b/specs/sell_logistics_v1_oas3.json
@@ -2,13 +2,13 @@
"openapi": "3.0.0",
"info": {
"title": "Logistics API",
- "description": "The Logistics API resources offer the following capabilities: - shipping_quote – Consolidates into a list a set of live shipping rates, or quotes, from which you can select a rate to ship a package.
- shipment – Creates a \"shipment\" for the selected shipping rate.
Call createShippingQuote to get a list of live shipping rates. The rates returned are all valid for a specific time window and all quoted prices are at eBay-negotiated rates.
Select one of the live rates and using its associated rateId, create a \"shipment\" for the package by calling createFromShippingQuote. Creating a shipment completes an agreement, and the cost of the base service and any added shipping options are summed into the returned totalShippingCost value. This action also generates a shipping label that you can use to ship the package. The total cost of the shipment is incurred when the package is shipped using the supplied shipping label. Important! Sellers must set up a payment method via their eBay account before they can use the methods in this API to create a shipment and the associated shipping label.
",
+ "description": "Note: This is a ![\"Limited](\"/cms/img/docs/partners-api.svg\" "\\"Limited")
(Limited Release) API available only to select developers approved by business units.
The Logistics API resources offer the following capabilities: - shipping_quote – Consolidates into a list a set of live shipping rates, or quotes, from which you can select a rate to ship a package.
- shipment – Creates a \"shipment\" for the selected shipping rate.
Call createShippingQuote to get a list of live shipping rates. The rates returned are all valid for a specific time window and all quoted prices are at eBay-negotiated rates.
Select one of the live rates and using its associated rateId, create a \"shipment\" for the package by calling createFromShippingQuote. Creating a shipment completes an agreement, and the cost of the base service and any added shipping options are summed into the returned totalShippingCost value. This action also generates a shipping label that you can use to ship the package. The total cost of the shipment is incurred when the package is shipped using the supplied shipping label. Important! Sellers must set up a payment method via their eBay account before they can use the methods in this API to create a shipment and the associated shipping label.
",
"contact": {
"name": "eBay Inc,"
},
"license": {
"name": "eBay API License Agreement",
- "url": "https://go.developer.ebay.com/api-license-agreement"
+ "url": "https://developer.ebay.com/join/api-license-agreement"
},
"version": "v1_beta.0.0"
},
@@ -24,128 +24,18 @@
}
],
"paths": {
- "/shipping_quote": {
+ "/shipment/{shipmentId}/cancel": {
"post": {
"tags": [
- "shipping_quote"
- ],
- "description": "The createShippingQuote method returns a shipping quote that contains a list of live "rates." Each rate represents an offer made by a shipping carrier for a specific service and each offer has a live quote for the base service cost. Rates have a time window in which they are "live," and rates expire when their purchase window ends. If offered by the carrier, rates can include shipping options (and their associated prices), and users can add any offered shipping option to the base service should they desire. Also, depending on the services required, rates can also include pickup and delivery windows. Each rate is for a single package and is based on the following information: The shipping origin The shipping destination The package size (weight and dimensions) Rates are identified by a unique eBay-assigned rateId and rates are based on price points, pickup and delivery time frames, and other user requirements. Because each rate offered must be compliant with the eBay shipping program, all rates reflect eBay-negotiated prices. The various rates returned in a shipping quote offer the user a choice from which they can choose a shipping service that best fits their needs. Select the rate for your shipment and using the associated rateId, call cerateFromShippingQuote to create a shipment and generate a shipping label that you can use to ship the package.",
- "operationId": "createShippingQuote",
- "requestBody": {
- "description": "The request object for createShippingQuote.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The request object for createShippingQuote.",
- "$ref": "#/components/schemas/ShippingQuoteRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "201": {
- "description": "Created",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ShippingQuote"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "90135": {
- "domain": "API_LOGISTICS",
- "category": "REQUEST",
- "description": "The provided shipTo address does not match the destination address of the order(s)."
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "90010": {
- "domain": "API_LOGISTICS",
- "category": "REQUEST",
- "description": "Missing field {fieldName}."
- },
- "90020": {
- "domain": "API_LOGISTICS",
- "category": "REQUEST",
- "description": "Invalid field {fieldName}."
- },
- "90110": {
- "domain": "API_LOGISTICS",
- "category": "REQUEST",
- "description": "The order {orderId} was not found on the platform."
- }
- }
- }
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "90100": {
- "domain": "API_LOGISTICS",
- "category": "REQUEST",
- "description": "No shipping services available for the provided addresses."
- },
- "90120": {
- "domain": "API_LOGISTICS",
- "category": "REQUEST",
- "description": "The package specification is incompatible with the destination."
- },
- "90130": {
- "domain": "API_LOGISTICS",
- "category": "REQUEST",
- "description": "Order {orderId} is incompatible with our services."
- },
- "90133": {
- "domain": "API_LOGISTICS",
- "category": "REQUEST",
- "description": "Maximum number of orders exceeded. Current limitation is 10."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "90000": {
- "domain": "API_LOGISTICS",
- "category": "APPLICATION",
- "description": "A system error has occurred."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.logistics"
- ]
- }
- ]
- }
- },
- "/shipping_quote/{shippingQuoteId}": {
- "get": {
- "tags": [
- "shipping_quote"
+ "shipment"
],
- "description": "This method retrieves the complete details of the shipping quote associated with the specified shippingQuoteId value. A "shipping quote" pertains to a single specific package and contains a set of shipping "rates" that quote the cost to ship the package by different shipping carriers and services. The quotes are based on the package's origin, destination, and size. Call createShippingQuote to create a shippingQuoteId.",
- "operationId": "getShippingQuote",
+ "description": "This method cancels the shipment associated with the specified shipment ID and the associated shipping label is deleted. When you cancel a shipment, the totalShippingCost of the canceled shipment is refunded to the account established by the user's billing agreement.
Note that you cannot cancel a shipment if you have used the associated shipping label.",
+ "operationId": "cancelShipment",
"parameters": [
{
- "name": "shippingQuoteId",
+ "name": "shipmentId",
"in": "path",
- "description": "This path parameter specifies the unique eBay-assigned ID of the shipping quote you want to retrieve. The shippingQuoteId value is generated and returned by a call to createShippingQuote.",
+ "description": "This path parameter specifies the unique eBay-assigned ID of the shipment to be canceled.
The shipmentId value is generated and returned by the createFromShippingQuote method.",
"required": true,
"schema": {
"type": "string"
@@ -158,7 +48,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/ShippingQuote"
+ "$ref": "#/components/schemas/Shipment"
}
}
}
@@ -178,6 +68,18 @@
}
}
},
+ "409": {
+ "description": "Conflict",
+ "x-response-codes": {
+ "errors": {
+ "90260": {
+ "domain": "API_LOGISTICS",
+ "category": "REQUEST",
+ "description": "Cannot cancel shipment {shipmentId}"
+ }
+ }
+ }
+ },
"500": {
"description": "Internal Server Error",
"x-response-codes": {
@@ -205,8 +107,28 @@
"tags": [
"shipment"
],
- "description": "This method creates a "shipment" based on the shippingQuoteId and rateId values supplied in the request. The rate identified by the rateId value specifies the carrier and service for the package shipment, and the rate ID must be contained in the shipping quote identified by the shippingQuoteId value. Call createShippingQuote to retrieve a set of live shipping rates. When you create a shipment, eBay generates a shipping label that you can download and use to ship your package. In a createFromShippingQuote request, sellers can include a list of shipping options they want to add to the base service quoted in the selected rate. The list of available shipping options is specific to each quoted rate and if available, the options are listed in the rate container of the of the shipping quote. In addition to a configurable return-to location and other details about the shipment, the response to this method includes: The shipping carrier and service to be used for the package shipment A list of selected shipping options, if any The shipment tracking number The total shipping cost (the sum cost of the base shipping service and any added options) When you create a shipment, your billing agreement account is charged the sum of the baseShippingCost and the total cost of any additional shipping options you might have selected. Use the URL returned in labelDownloadUrl field, or call downloadLabelFile with the shipmentId value from the response, to download a shipping label for your package. Important! Sellers must set up their payment method with eBay before they can use this method to create a shipment and the associated shipping label.",
+ "description": "This method creates a shipment based on the shippingQuoteId and rateId values supplied in the request. The rate identified by the rateId value specifies the carrier and service for the package shipment, and the rate ID must be contained in the shipping quote identified by the shippingQuoteId value. Call createShippingQuote to retrieve a set of live shipping rates.
Note: The Logistics API only supports USPS shipping rates and labels.
When you create a shipment, eBay generates a shipping label that you can download and use to ship your package.
In a createFromShippingQuote request, sellers can include a list of shipping options they want to add to the base service quoted in the selected rate. The list of available shipping options is specific to each quoted rate and if available, the options are listed in the rate container of the shipping quote.
In addition to a configurable return-to location and other details about the shipment, the response to this method includes:- The shipping carrier and service to be used for the package shipment
- A list of selected shipping options, if any
- The shipment tracking number
- The total shipping cost (the sum cost of the base shipping service and any added options)
When you create a shipment, your billing agreement account is charged the sum of the baseShippingCost and the total cost of any additional shipping options you might have selected. Use the URL returned in labelDownloadURL field, or call downloadLabelFile with the shipmentId value from the response, to download a shipping label for your package.
Important! Sellers must set up their payment method before they can use this method to create a shipment and the associated shipping label.
Set up a billing agreement
Prior to using this method to create a shipment, sellers must first set up their billing agreement. Failure to do so will return Error 90030 Payment could not be completed.
The preferred method for sellers to set up their billing agreement is to go to Set up billing agreement and follow the on-screen directions.
Alternatively, sellers can do the following:- Go to https://www.ebay.com/ship/single/{order_id}, where {order_id} is that of the order for which the label is being printed.
- When prompted, select PayPal.
- Verify that Save PayPal for future purchases is selected.
- Click Set up Payments which will open PayPal in a pop-up window.
- Log in using PayPal credentials, and then follow the on-screen prompts to set up the billing agreement.
- Once the agreement has been set up, sellers can leave this page as there is no need to actually print a label.
",
"operationId": "createFromShippingQuote",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header parameter specifies the eBay marketplace for the shipment being created.
For a list of valid values, refer to the section Marketplace ID Values in the Using eBay RESTful APIs guide.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
"requestBody": {
"description": "The create shipment from quote request.",
"content": {
@@ -291,18 +213,27 @@
]
}
},
- "/shipment/{shipmentId}": {
+ "/shipment/{shipmentId}/download_label_file": {
"get": {
"tags": [
"shipment"
],
- "description": "This method retrieves the shipment details for the specified shipment ID. Call createFromShippingQuote to generate a shipment ID.",
- "operationId": "getShipment",
+ "description": "This method returns the shipping label file that was generated for the shipmentId value specified in the request. Call createFromShippingQuote to generate a shipment ID.
Note: The Logistics API only supports USPS shipping rates and labels.
Use the Accept HTTP header to specify the format of the returned file. The default file format is a PDF file. ",
+ "operationId": "downloadLabelFile",
"parameters": [
{
"name": "shipmentId",
"in": "path",
- "description": "This path parameter specifies the unique eBay-assigned ID of the shipment you want to retrieve. The shipmentId value is generated and returned by a call to createFromShippingQuote.",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the shipment associated with the shipping label you want to download.
The shipmentId value is generated and returned by the createFromShippingQuote method.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept",
+ "in": "header",
+ "description": "This header specifies the format of the returned file. For this method, the value of the header should be Accept: application/pdf. ",
"required": true,
"schema": {
"type": "string"
@@ -313,9 +244,12 @@
"200": {
"description": "Success",
"content": {
- "application/json": {
+ "application/pdf": {
"schema": {
- "$ref": "#/components/schemas/Shipment"
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
}
}
}
@@ -357,18 +291,18 @@
]
}
},
- "/shipment/{shipmentId}/download_label_file": {
+ "/shipment/{shipmentId}": {
"get": {
"tags": [
"shipment"
],
- "description": "This method returns the shipping label file that was generated for the shipmentId value specified in the request. Call createFromShippingQuote to generate a shipment ID. Use the Accept HTTP header to specify the format of the returned file. The default file format is a PDF file.",
- "operationId": "downloadLabelFile",
+ "description": "This method retrieves the shipment details for the specified shipment ID. Call createFromShippingQuote to generate a shipment ID.",
+ "operationId": "getShipment",
"parameters": [
{
"name": "shipmentId",
"in": "path",
- "description": "This path parameter specifies the unique eBay-assigned ID of the shipment associated with the shipping label you want to download. The shipmentId value is generated and returned by a call to createFromShippingQuote.",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the shipment you want to retrieve.
The shipmentId value is generated and returned by the createFromShippingQuote method.",
"required": true,
"schema": {
"type": "string"
@@ -379,12 +313,9 @@
"200": {
"description": "Success",
"content": {
- "application/pdf": {
+ "application/json": {
"schema": {
- "type": "array",
- "items": {
- "type": "string"
- }
+ "$ref": "#/components/schemas/Shipment"
}
}
}
@@ -426,46 +357,83 @@
]
}
},
- "/shipment/{shipmentId}/cancel": {
+ "/shipping_quote": {
"post": {
"tags": [
- "shipment"
+ "shipping_quote"
],
- "description": "This method cancels the shipment associated with the specified shipment ID and the associated shipping label is deleted. When you cancel a shipment, the totalShippingCost of the canceled shipment is refunded to the account established by the user's billing agreement. Note that you cannot cancel a shipment if you have used the associated shipping label.",
- "operationId": "cancelShipment",
+ "description": "The createShippingQuote method returns a shipping quote that contains a list of live \"rates.\"
Each rate represents an offer made by a shipping carrier for a specific service and each offer has a live quote for the base service cost. Rates have a time window in which they are \"live,\" and rates expire when their purchase window ends. If offered by the carrier, rates can include shipping options (and their associated prices), and users can add any offered shipping option to the base service should they desire. Also, depending on the services required, rates can also include pickup and delivery windows.
Note: The Logistics API only supports USPS shipping rates and labels.
Each rate is for a single package and is based on the following information: - The shipping origin
- The shipping destination
- The package size (weight and dimensions)
Rates are identified by a unique eBay-assigned rateId and rates are based on price points, pickup and delivery time frames, and other user requirements. Because each rate offered must be compliant with the eBay shipping program, all rates reflect eBay-negotiated prices.
The various rates returned in a shipping quote offer the user a choice from which they can choose a shipping service that best fits their needs. Select the rate for your shipment and using the associated rateId, call createFromShippingQuote to create a shipment and generate a shipping label that you can use to ship the package.",
+ "operationId": "createShippingQuote",
"parameters": [
{
- "name": "shipmentId",
- "in": "path",
- "description": "This path parameter specifies the unique eBay-assigned ID of the shipment to be canceled. The shipmentId value is generated and returned by a call to createFromShippingQuote.",
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header parameter specifies the eBay marketplace for the shipping quote that is being created.
For a list of valid values, refer to the section Marketplace ID Values in the Using eBay RESTful APIs guide.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
"required": true,
"schema": {
"type": "string"
}
}
],
+ "requestBody": {
+ "description": "The request object for createShippingQuote.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The request object for createShippingQuote.",
+ "$ref": "#/components/schemas/ShippingQuoteRequest"
+ }
+ }
+ },
+ "required": true
+ },
"responses": {
- "200": {
- "description": "Success",
+ "201": {
+ "description": "Created",
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/Shipment"
+ "$ref": "#/components/schemas/ShippingQuote"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "90135": {
+ "domain": "API_LOGISTICS",
+ "category": "REQUEST",
+ "description": "The provided shipTo address does not match the destination address of the order(s)."
}
}
}
},
"400": {
- "description": "Bad Request"
- },
- "404": {
- "description": "Not Found",
+ "description": "Bad Request",
"x-response-codes": {
"errors": {
- "90005": {
+ "90010": {
"domain": "API_LOGISTICS",
"category": "REQUEST",
- "description": "The resource could not be found."
+ "description": "Missing field {fieldName}."
+ },
+ "90020": {
+ "domain": "API_LOGISTICS",
+ "category": "REQUEST",
+ "description": "Invalid field {fieldName}."
+ },
+ "90110": {
+ "domain": "API_LOGISTICS",
+ "category": "REQUEST",
+ "description": "The order {orderId} was not found on the platform."
}
}
}
@@ -474,10 +442,91 @@
"description": "Conflict",
"x-response-codes": {
"errors": {
- "90260": {
+ "90100": {
"domain": "API_LOGISTICS",
"category": "REQUEST",
- "description": "Cannot cancel shipment {shipmentId}"
+ "description": "No shipping services available for the provided addresses."
+ },
+ "90120": {
+ "domain": "API_LOGISTICS",
+ "category": "REQUEST",
+ "description": "The package specification is incompatible with the destination."
+ },
+ "90130": {
+ "domain": "API_LOGISTICS",
+ "category": "REQUEST",
+ "description": "Order {orderId} is incompatible with our services."
+ },
+ "90133": {
+ "domain": "API_LOGISTICS",
+ "category": "REQUEST",
+ "description": "Maximum number of orders exceeded. Current limitation is 10."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "90000": {
+ "domain": "API_LOGISTICS",
+ "category": "APPLICATION",
+ "description": "A system error has occurred."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.logistics"
+ ]
+ }
+ ]
+ }
+ },
+ "/shipping_quote/{shippingQuoteId}": {
+ "get": {
+ "tags": [
+ "shipping_quote"
+ ],
+ "description": "This method retrieves the complete details of the shipping quote associated with the specified shippingQuoteId value.
A \"shipping quote\" pertains to a single specific package and contains a set of shipping \"rates\" that quote the cost to ship the package by different shipping carriers and services. The quotes are based on the package's origin, destination, and size.
Call createShippingQuote to create a shippingQuoteId.",
+ "operationId": "getShippingQuote",
+ "parameters": [
+ {
+ "name": "shippingQuoteId",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned ID of the shipping quote you want to retrieve.
The shippingQuoteId value is generated and returned by the createShippingQuote method.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ShippingQuote"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request"
+ },
+ "404": {
+ "description": "Not Found",
+ "x-response-codes": {
+ "errors": {
+ "90005": {
+ "domain": "API_LOGISTICS",
+ "category": "REQUEST",
+ "description": "The resource could not be found."
}
}
}
@@ -511,7 +560,7 @@
"type": "object",
"properties": {
"additionalCost": {
- "description": "The monetary cost of the additional shipping option identified by the optionType field.",
+ "description": "The monetary cost of the additional shipping option identified by the optionType field.",
"$ref": "#/components/schemas/Amount"
},
"optionType": {
@@ -526,11 +575,11 @@
"properties": {
"currency": {
"type": "string",
- "description": "The base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD. Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation"
+ "description": "The base currency applied to the value field to establish a monetary amount.
The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.
Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation"
},
"value": {
"type": "string",
- "description": "The monetary amount in the specified currency."
+ "description": "The monetary amount in the specified currency.
Required in the amount type."
}
},
"description": "A complex type that describes the value of a monetary amount as represented by a global currency."
@@ -574,7 +623,7 @@
},
"countryCode": {
"type": "string",
- "description": "The country of the address, represented as two-letter ISO 3166 country code. For example, US represents the United States and DE represents Germany. For implementation help, refer to eBay API documentation"
+ "description": "The country of the address, represented as two-letter ISO 3166 country code. For example, US represents the United States and DE represents Germany. For implementation help, refer to eBay API documentation"
},
"county": {
"type": "string",
@@ -596,7 +645,7 @@
"properties": {
"additionalOptions": {
"type": "array",
- "description": "Supply a list of one or more shipping options that the seller wants to purchase for this shipment. The baseShippingCost field that's associated with the selected shipping rate is the cost of the base service offered in the rate. In addition to the base service, sellers can add additional shipping services to the base service. Shipping options include things such as shipping insurance or a recipient's signature upon delivery. The cost of any added services is summed with the base shipping cost to determine the final cost for the shipment. All options added to the shipment must be chosen from the set of shipping options offered with the selected rate.",
+ "description": "Supply a list of one or more shipping options that the seller wants to purchase for this shipment.
The baseShippingCost field that's associated with the selected shipping rate is the cost of the base service offered in the rate. In addition to the base service, sellers can add additional shipping services to the base service. Shipping options include things such as shipping insurance or a recipient's signature upon delivery. The cost of any added services is summed with the base shipping cost to determine the final cost for the shipment. All options added to the shipment must be chosen from the set of shipping options offered with the selected rate.",
"items": {
"$ref": "#/components/schemas/AdditionalOption"
}
@@ -607,22 +656,22 @@
},
"labelSize": {
"type": "string",
- "description": "The seller's desired label size. Any supplied value is applied only if the shipping carrier supports multiple label sizes, otherwise the carrier's default label size is used. 4"x6""
+ "description": "The seller's desired label size. Any supplied value is applied only if the shipping carrier supports multiple label sizes, otherwise the carrier's default label size is used.
Currently, the only valid value is: 4\"x6\""
},
"rateId": {
"type": "string",
- "description": "The eBay-assigned ID of the shipping rate that the seller selected for the shipment. This value is generated by a call to createShippingQuote and is returned in the rates.rateId field."
+ "description": "The unique eBay-assigned identifier of the shipping rate that the seller selected for the shipment. This value is generated by using the createShippingQuote method and is returned in the rates.rateId field."
},
"returnTo": {
- "description": "The optional return address and contact details for the shipment. The return address is printed on the shipping label. If not specified, the return address defaults to the shipFrom address returned in shipping quote.",
+ "description": "The optional return address and contact details for the shipment. The return address is printed on the shipping label. If not specified, the return address defaults to the shipFrom address returned in shipping quote. ",
"$ref": "#/components/schemas/Contact"
},
"shippingQuoteId": {
"type": "string",
- "description": "The unique eBay-assigned ID of the shipping quote that was generated by a call to createShippingQuote."
+ "description": "The unique eBay-assigned identifier of the shipping quote that was generated by the createShippingQuote method."
}
},
- "description": "This complex type contains the request payload for the createFromShippingQuote method."
+ "description": "This complex type contains the request payload for the createFromShippingQuote method."
},
"Dimensions": {
"type": "object",
@@ -651,7 +700,7 @@
"properties": {
"category": {
"type": "string",
- "description": "The category type for this error or warning. It takes a string that can have one of three values: Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency. Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as "Seller does not ship item to Antarctica" or "Buyer ineligible to purchase an alcoholic item". Business errors are not syntactical input errors. Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on."
+ "description": "The category type for this error or warning. It takes a string that can have one of three values:Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as \"Seller does not ship item to Antarctica\" or \"Buyer ineligible to purchase an alcoholic item\". Business errors are not syntactical input errors.Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.
"
},
"domain": {
"type": "string",
@@ -664,7 +713,7 @@
},
"inputRefIds": {
"type": "array",
- "description": "Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.",
+ "description": "Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.",
"items": {
"type": "string"
}
@@ -679,14 +728,14 @@
},
"outputRefIds": {
"type": "array",
- "description": "Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.",
+ "description": "Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.",
"items": {
"type": "string"
}
},
"parameters": {
"type": "array",
- "description": "This optional complex field type contains a list of one or more context-specific ErrorParameter objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.",
+ "description": "This optional complex field type contains a list of one or more context-specific ErrorParameter objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.",
"items": {
"$ref": "#/components/schemas/ErrorParameter"
}
@@ -717,11 +766,11 @@
"properties": {
"channel": {
"type": "string",
- "description": "The e-commerce platform or environment where the order was created. Use the value EBAY to get the rates available for eBay orders."
+ "description": "The marketplace where the order was created.
Use the value EBAY to get the rates available for eBay orders."
},
"orderId": {
"type": "string",
- "description": "The unique ID of the order supplied by the channel of origin. For eBay orders, this would be the orderId."
+ "description": "The unique identifier of the order. The getOrders method of the Fulfillment API can be used to retrieve order IDs."
}
},
"description": "This complex type defines an order from which a seller is including one or more line items in a single package to be shipped."
@@ -755,19 +804,19 @@
"properties": {
"pickupSlotEndTime": {
"type": "string",
- "description": "The date and time the pickup slot ends, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Format: [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS].[SSS]Z Example: 2018-08-20T07:09:00.000Z"
+ "description": "The date and time the pickup slot ends, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2018-08-20T07:09:00.000Z"
},
"pickupSlotId": {
"type": "string",
- "description": "Seller-defined name for the pickup slot."
+ "description": "Seller-defined name for the pickup slot. "
},
"pickupSlotStartTime": {
"type": "string",
- "description": "The date and time the pickup slot begins, formatted as an ISO 8601 UTC string."
+ "description": "The date and time the pickup slot begins, formatted as an ISO 8601 UTC string."
},
"pickupSlotTimeZone": {
"type": "string",
- "description": "The time zone of the pickup location, returned as Time Zone Database ID (also know as an Olson time zone ID)."
+ "description": "The time zone of the pickup location, returned as Time Zone Database ID (also know as an Olson time zone ID)."
}
},
"description": "This complex type defines a time window for the pickup of a package."
@@ -783,20 +832,20 @@
}
},
"baseShippingCost": {
- "description": "The amount of the "base cost" for the shipment as set by the given carrier for the specified service. This cost excludes any addition costs accrued from the addition of any optional shipping options.",
+ "description": "The amount of the \"base cost\" for the shipment as set by the given carrier for the specified service. This cost excludes any addition costs accrued from the addition of any optional shipping options.",
"$ref": "#/components/schemas/Amount"
},
"destinationTimeZone": {
"type": "string",
- "description": "The time zone of the destination according to Time Zone Database. For example, "America/Los_Angeles"."
+ "description": "The time zone of the destination according to Time Zone Database. For example, \"America/Los_Angeles\"."
},
"maxEstimatedDeliveryDate": {
"type": "string",
- "description": "A string value representing maximum (latest) estimated delivery time, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Format: [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS].[SSS]Z Example: 2018-08-20T07:09:00.000Z"
+ "description": "A string value representing maximum (latest) estimated delivery time, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2018-08-20T07:09:00.000Z"
},
"minEstimatedDeliveryDate": {
"type": "string",
- "description": "A string value representing minimum (earliest) estimated delivery time, formatted as an ISO 8601ISO 8601 UTC string."
+ "description": "A string value representing minimum (earliest) estimated delivery time, formatted as an ISO 8601ISO 8601 UTC string."
},
"pickupNetworks": {
"type": "array",
@@ -827,7 +876,7 @@
},
"shippingQuoteId": {
"type": "string",
- "description": "The unique eBay-generated ID of the shipping quote from which the seller selected a shipping rate (rateId)."
+ "description": "The unique eBay-generated ID of the shipping quote from which the seller selected a shipping rate (rateId)."
},
"shippingServiceCode": {
"type": "string",
@@ -842,29 +891,29 @@
"$ref": "#/components/schemas/Amount"
}
},
- "description": "The "rate" that has been selected and purchased for the shipment, as referenced by the rateId value."
+ "description": "The \"rate\" that has been selected and purchased for the shipment, as referenced by the rateId value."
},
"Rate": {
"type": "object",
"properties": {
"additionalOptions": {
"type": "array",
- "description": "Contains service and pricing information for one or more shipping options that are offered by the carrier and can be purchased in addition to the base shipping service provided by this rate. Shipping options can include items such as INSURANCE and SIGNATURE.",
+ "description": "Contains service and pricing information for one or more shipping options that are offered by the carrier and can be purchased in addition to the base shipping service provided by this rate. Shipping options can include items such as INSURANCE and SIGNATURE.",
"items": {
"$ref": "#/components/schemas/AdditionalOption"
}
},
"baseShippingCost": {
- "description": "A live quote for the cost that the carrier (identified by shippingCarrierCode) is charging for the shipping service being offered (identified by shippingServiceCode), excluding any additional shipping options.",
+ "description": "A live quote for the cost that the carrier (identified by shippingCarrierCode) is charging for the shipping service being offered (identified by shippingServiceCode), excluding any additional shipping options.",
"$ref": "#/components/schemas/Amount"
},
"destinationTimeZone": {
"type": "string",
- "description": "The name of the time zone region, as defined in the IANA Time Zone Database, to which the package is being shipped. Delivery dates are calculated relative to this time zone. Note: This is different from a Coordinated Universal Time (UTC) offset. For example, the America/Los_Angeles time zone identifies a region with the UTC standard time offset of -08:00, but so do several other time zones, including America/Tijuana,America/Dawson, and Pacific/Pitcairn."
+ "description": "The name of the time zone region, as defined in the IANA Time Zone Database, to which the package is being shipped.
Delivery dates are calculated relative to this time zone.
Note: This is different from a Coordinated Universal Time (UTC) offset. For example, the America/Los_Angeles time zone identifies a region with the UTC standard time offset of -08:00, but so do several other time zones, including America/Tijuana,America/Dawson, and Pacific/Pitcairn."
},
"maxEstimatedDeliveryDate": {
"type": "string",
- "description": "The latest stated date and time the shipment will be delivered at this rate. The time stamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Format: [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS].[SSS]Z Example: 2018-08-20T07:09:00.000Z"
+ "description": "The latest stated date and time the shipment will be delivered at this rate.
The time stamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2018-08-20T07:09:00.000Z"
},
"minEstimatedDeliveryDate": {
"type": "string",
@@ -886,7 +935,7 @@
},
"pickupType": {
"type": "string",
- "description": "The type of pickup or drop-off service associated with the pickupSlots time frames. For implementation help, refer to eBay API documentation"
+ "description": "The type of pickup or drop-off service associated with the pickupSlots time frames. For implementation help, refer to eBay API documentation"
},
"rateId": {
"type": "string",
@@ -894,7 +943,7 @@
},
"rateRecommendation": {
"type": "array",
- "description": "A list of reasons this rate is recommended. Available values are: BUYER_CHOSEN — The rate meets or exceeds the requirements of the buyer's preferred shipping option. CHEAPEST_ON_TIME — The rate is the cheapest rate available that will provide delivery within the seller's time frame commitment. EBAY_PLUS_OK — The rate complies with the shipping requirements of the eBay Plus program. FASTEST_ON_TIME — The rate has the fastest shipping time, and will provide delivery within the seller's time frame commitment. GUARANTEED_DELIVERY_OK — The rate complies with the shipping requirements of the eBay Guaranteed Delivery program.",
+ "description": "A list of reasons this rate is recommended. Available values are: BUYER_CHOSEN — The rate meets or exceeds the requirements of the buyer's preferred shipping option.CHEAPEST_ON_TIME — The rate is the cheapest rate available that will provide delivery within the seller's time frame commitment.EBAY_PLUS_OK — The rate complies with the shipping requirements of the eBay Plus program.FASTEST_ON_TIME — The rate has the fastest shipping time, and will provide delivery within the seller's time frame commitment.GUARANTEED_DELIVERY_OK — The rate complies with the shipping requirements of the eBay Guaranteed Delivery program.
",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
@@ -902,7 +951,7 @@
},
"shippingCarrierCode": {
"type": "string",
- "description": "The code name of the shipping carrier who will provide the service identified by shippingServiceCode."
+ "description": "The code name of the shipping carrier who will provide the service identified by shippingServiceCode."
},
"shippingCarrierName": {
"type": "string",
@@ -910,7 +959,7 @@
},
"shippingServiceCode": {
"type": "string",
- "description": "The code name of the shipping service to be provided by the carrier identified by shippingCarrierCode."
+ "description": "The code name of the shipping service to be provided by the carrier identified by shippingCarrierCode."
},
"shippingServiceName": {
"type": "string",
@@ -928,7 +977,7 @@
},
"creationDate": {
"type": "string",
- "description": "The date and time the shipment was created, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Format: [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS].[SSS]Z Example: 2018-08-20T07:09:00.000Z"
+ "description": "The date and time the shipment was created, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2018-08-20T07:09:00.000Z"
},
"labelCustomMessage": {
"type": "string",
@@ -936,15 +985,15 @@
},
"labelDownloadUrl": {
"type": "string",
- "description": "The direct URL the seller can use to download an image of the shipping label. By default, the file format is PDF. See downloadLabelFile for requesting different response file formats."
+ "description": "The direct URL the seller can use to download an image of the shipping label. By default, the file format is PDF. See downloadLabelFile for requesting different response file formats."
},
"labelSize": {
"type": "string",
- "description": "The seller's desired label size. The support for multi-sized labels is shipping-carrier specific and if the size requested in the creaateFromShippingQuote call matches a size the carrier supports, the value will be represented here in the shipment. Currently, the only valid value is: 4"x6""
+ "description": "The seller's desired label size. The support for multi-sized labels is shipping-carrier specific and if the size requested in the creaateFromShippingQuote call matches a size the carrier supports, the value will be represented here in the shipment.
Currently, the only valid value is: 4\"x6\""
},
"orders": {
"type": "array",
- "description": "This list value is optionally assigned by the seller. When present, each element in the returned list contains seller-assigned information about an order (such as an order number). Because a package can contain all or part of one or more orders, this field provides a way for sellers to identify the packages that contain specific orders.",
+ "description": "A list of one or more orders that will be shipped in the shipping package.",
"items": {
"$ref": "#/components/schemas/Order"
}
@@ -954,11 +1003,11 @@
"$ref": "#/components/schemas/PackageSpecification"
},
"rate": {
- "description": "The shipping rate that the seller has chosen to purchase for this shipment. Each rate, identified by a rateId, contains the offered base service, options, and shipping parameters that were selected for the package shipment.",
+ "description": "The shipping rate that the seller has chosen to purchase for this shipment. Each rate, identified by a rateId, contains the offered base service, options, and shipping parameters that were selected for the package shipment.",
"$ref": "#/components/schemas/PurchasedRate"
},
"returnTo": {
- "description": "The address and contact details that should be used for item returns. Sellers have the option to define a return address that is different from their shipFrom address. If not specified, the return address defaults to the shipFrom address in the shipping quote.",
+ "description": "The address and contact details that should be used for item returns. Sellers have the option to define a return address that is different from their shipFrom address. If not specified, the return address defaults to the shipFrom address in the shipping quote.",
"$ref": "#/components/schemas/Contact"
},
"shipFrom": {
@@ -967,7 +1016,7 @@
},
"shipmentId": {
"type": "string",
- "description": "The unique eBay-assigned ID for the shipment. The ID is generated when the shipment is created by a call to createFromShippingQuote."
+ "description": "The unique eBay-assigned ID for the shipment. The ID is generated when the shipment is created by a call to createFromShippingQuote."
},
"shipmentTrackingNumber": {
"type": "string",
@@ -978,14 +1027,14 @@
"$ref": "#/components/schemas/Contact"
}
},
- "description": "This complex type defines a shipment for a specific package (for example, a box or letter). Shipments are always linked to a purchased shipping label."
+ "description": "This complex type defines a shipment for a specific package (for example, a box or letter). Shipments are always linked to a purchased shipping label. "
},
"ShipmentCancellation": {
"type": "object",
"properties": {
"cancellationRequestedDate": {
"type": "string",
- "description": "The time and date the request was made to cancel the shipment, formatted as an ISO 8601 UTC string."
+ "description": "The time and date the request was made to cancel the shipment, formatted as an ISO 8601 UTC string."
},
"cancellationStatus": {
"type": "string",
@@ -1007,7 +1056,7 @@
},
"orders": {
"type": "array",
- "description": "This list value is optionally assigned by the seller. When present, each element in the returned list contains seller-assigned information about an order (such as an order number). Because a package can contain all or part of one or more orders, this field provides a way for sellers to identify the packages that contain specific orders.",
+ "description": "A list of one or more orders that will be shipped in the shipping package.",
"items": {
"$ref": "#/components/schemas/Order"
}
@@ -1018,7 +1067,7 @@
},
"rates": {
"type": "array",
- "description": "A list of rates where each rate, as identified by a rateId, contains information about a specific shipping service offered by a carrier. Rates include shipping carrier and service, the to and from locations, the pickup and delivery windows, the seller's shipping parameters, the service constraints, and the cost for the base service and a list of additional shipping options. Each rate offered is supported by a label service where you can purchase the rate, and associated shipping label, via a call to createFromShippingQuote.",
+ "description": "A list of rates where each rate, as identified by a rateId, contains information about a specific shipping service offered by a carrier. Rates include shipping carrier and service, the to and from locations, the pickup and delivery windows, the seller's shipping parameters, the service constraints, and the cost for the base service and a list of additional shipping options.
Note: The Logistics API only supports USPS shipping rates and labels.
Each rate offered is supported by a label service where you can purchase the rate, and associated shipping label, via a call to createFromShippingQuote.",
"items": {
"$ref": "#/components/schemas/Rate"
}
@@ -1032,7 +1081,7 @@
"description": "The unique eBay-assigned ID for this shipping quote. The value of this field is associated with a specific package, based on its origin, destination, and size."
},
"shipTo": {
- "description": "The address and contact details for the origin of the shipment.",
+ "description": "The address and contact details for the origin of the shipment. ",
"$ref": "#/components/schemas/Contact"
},
"warnings": {
@@ -1043,14 +1092,14 @@
}
}
},
- "description": "This complex type describes a "shipping quote," which contains the parameters for a package shipment. The shipping quote contains a list of "live quotes" or rates for the shipment. Rates are offerd by a carrier for a particular service, of set of services, for shipping the package. Included in the shipping quote are the package specifications, the shipment's origin and destination addresses, and the shipping parameters specified by the seller. Use the rateId value to select the specific service you want when you create a shipment by calling createFromShippingQuote."
+ "description": "This complex type describes a \"shipping quote,\" which contains the parameters for a package shipment. The shipping quote contains a list of \"live quotes\" or rates for the shipment. Rates are offerd by a carrier for a particular service, of set of services, for shipping the package. Included in the shipping quote are the package specifications, the shipment's origin and destination addresses, and the shipping parameters specified by the seller.
Use the rateId value to select the specific service you want when you create a shipment by calling createFromShippingQuote."
},
"ShippingQuoteRequest": {
"type": "object",
"properties": {
"orders": {
"type": "array",
- "description": "A seller-defined list that contains information about the orders in the package. This allows sellers to include information about the line items in the package with the shipment information. A package can contain any number of line items from one or more orders, providing they all ship in the same package. Maximum list size: 10",
+ "description": "In this array, the seller specifies one or more orders that will be shipped in the shipping package.
A shipping package can contain any number of line items from one or more orders, providing they all ship in the same package.
Maximum list size: 10",
"items": {
"$ref": "#/components/schemas/Order"
}
@@ -1068,18 +1117,18 @@
"$ref": "#/components/schemas/Contact"
}
},
- "description": "This complex type defines the request body for createShippingQuote. Sellers request a quote for a shipment by defining the "To" and "From" addresses for the package, plus the package's size. Carriers respond by offering up a "rate" for the service of theirs that best fits seller's needs."
+ "description": "This complex type defines the request body for createShippingQuote. Sellers request a quote for a shipment by defining the \"To\" and \"From\" addresses for the package, plus the package's size.
Carriers respond by offering up a \"rate\" for the service of theirs that best fits seller's needs."
},
"Weight": {
"type": "object",
"properties": {
"unit": {
"type": "string",
- "description": "The unit of measurement used to specify the weight of a shipping package. Both the unit and value fields are required if the weight container is used. If the English system of measurement is being used, the applicable values for weight units are POUND and OUNCE. If the metric system of measurement is being used, the applicable values for weight units are KILOGRAM and GRAM. The metric system is used by most countries outside of the US. For implementation help, refer to eBay API documentation"
+ "description": "The unit of measurement used to specify the weight of a shipping package. Both the unit and value fields are required if the weight container is used. If the English system of measurement is being used, the applicable values for weight units are POUND and OUNCE. If the metric system of measurement is being used, the applicable values for weight units are KILOGRAM and GRAM. The metric system is used by most countries outside of the US. For implementation help, refer to eBay API documentation"
},
"value": {
"type": "string",
- "description": "The numeric value of the weight of the package, as measured by the value of unit."
+ "description": "The numeric value of the weight of the package, as measured by the value of unit."
}
},
"description": "This complex type contains information about the weight of an object such as a shipping package."
diff --git a/specs/sell_marketing_v1_oas3.json b/specs/sell_marketing_v1_oas3.json
index b9dfc3d4..9e4c528b 100644
--- a/specs/sell_marketing_v1_oas3.json
+++ b/specs/sell_marketing_v1_oas3.json
@@ -1,15651 +1,18555 @@
{
- "openapi": "3.0.0",
- "info": {
- "title": "Marketing API",
- "description": "The Marketing API offers two platforms that sellers can use to promote and advertise their products:
- Promoted Listings is an eBay ad service that lets sellers set up ad campaigns for the products they want to promote. eBay displays the ads in search results and in other marketing modules as SPONSORED listings. If an item in a Promoted Listings campaign sells, the seller is assessed a Promoted Listings fee, which is a seller-specified percentage applied to the sales price. For complete details, refer to the Promoted Listings playbook.
- Promotions Manager gives sellers a way to offer discounts on specific items as a way to attract buyers to their inventory. Sellers can set up discounts (such as \"20% off\" and other types of offers) on specific items or on an entire customer order. To further attract buyers, eBay prominently displays promotion teasers throughout buyer flows. For complete details, see Promotions Manager.
Marketing reports, on both the Promoted Listings and Promotions Manager platforms, give sellers information that shows the effectiveness of their marketing strategies. The data gives sellers the ability to review and fine tune their marketing efforts.
Store Email Campaign allows sellers to create and send email campaigns to customers who have signed up to receive their newsletter. For more information on email campaigns, see Store Email Campaigns.
Important! Sellers must have an active eBay Store subscription, and they must accept the Terms and Conditions before they can make requests to these APIs in the Production environment. There are also site-specific listings requirements and restrictions associated with these marketing tools, as listed in the \"requirements and restrictions\" sections for Promoted Listings and Promotions Manager.
The table below lists all the Marketing API calls grouped by resource.
",
- "contact": {
- "name": "eBay Inc,"
- },
- "license": {
- "name": "eBay API License Agreement",
- "url": "https://go.developer.ebay.com/api-license-agreement"
- },
- "version": "v1.17.0"
- },
- "servers": [
- {
- "url": "https://api.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/marketing/v1"
- }
- }
- }
- ],
- "paths": {
- "/ad_campaign/{campaign_id}/bulk_create_ads_by_inventory_reference": {
- "post": {
- "tags": [
- "ad"
- ],
- "description": "This method adds multiple listings that are managed with the Inventory API to an existing Promoted Listings campaign.
For Promoted Listings Standard (PLS) campaigns using the Cost Per Sale (CPS) model, bulk ads may be directly created for the listing.
For each listing specified in the request, this method:
- Creates an ad for the listing.
- Sets the bid percentage (also known as the ad rate) for the ads created.
- Associates the ads created with the specified campaign.
To create ads for a listing, specify their inventoryReferenceId and inventoryReferenceType, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to which you want to associate the ads using the campaign_id path parameter.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.
Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.",
- "operationId": "bulkCreateAdsByInventoryReference",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created. Get a seller's campaign IDs by calling getCampaigns.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "The container for the bulk request to create ads for eBay inventory reference IDs. eBay inventory reference IDs are seller-defined IDs used by theInventory API.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The container for the bulk request to create ads for eBay inventory reference IDs. eBay inventory reference IDs are seller-defined IDs used by theInventory API.",
- "$ref": "#/components/schemas/BulkCreateAdsByInventoryReferenceRequest"
- }
- }
- },
- "required": true
+ "openapi": "3.0.0",
+ "info": {
+ "title": "Marketing API",
+ "description": "The Marketing API offers two platforms that sellers can use to promote and advertise their products:
- Promoted Listings is an eBay ad service that lets sellers set up ad campaigns for the products they want to promote. eBay displays the ads in search results and in other marketing modules as SPONSORED listings. If an item in a Promoted Listings campaign sells, the seller is assessed a Promoted Listings fee, which is a seller-specified percentage applied to the sales price. For complete details, refer to the Promoted Listings playbook.
- Promotions Manager gives sellers a way to offer discounts on specific items as a way to attract buyers to their inventory. Sellers can set up discounts (such as \"20% off\" and other types of offers) on specific items or on an entire customer order. To further attract buyers, eBay prominently displays promotion teasers throughout buyer flows. For complete details, see Promotions Manager.
Marketing reports, on both the Promoted Listings and Promotions Manager platforms, give sellers information that shows the effectiveness of their marketing strategies. The data gives sellers the ability to review and fine tune their marketing efforts.
Store Email Campaign allows sellers to create and send email campaigns to customers who have signed up to receive their newsletter. For more information on email campaigns, see Store Email Campaigns.
Important! Sellers must have an active eBay Store subscription, and they must accept the Terms and Conditions before they can make requests to these APIs in the Production environment. There are also site-specific listings requirements and restrictions associated with these marketing tools, as listed in the \"requirements and restrictions\" sections for Promoted Listings and Promotions Manager.
The table below lists all the Marketing API calls grouped by resource.
",
+ "contact": {
+ "name": "eBay Inc,"
},
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkCreateAdsByInventoryReferenceResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
- },
- "35010": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The bidPercentage should not be provided when selected adRateStrategy is DYNAMIC for the campaign."
- },
- "35012": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference ID {inventoryReferenceId} is not valid."
- },
- "35018": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
- },
- "35033": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one request is required for bulk requests."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35040": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36106": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'adGroupId' is not supported for CPS funding model."
- },
- "36108": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'adGroupId' is required for CPC funding model."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No adgroup found for adgroup id {ad_group_id}."
- },
- "36219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The ad group with ad group id {ad_group_id} has been archived."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35071": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
- },
- "35072": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP'."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
+ "license": {
+ "name": "eBay API License Agreement",
+ "url": "https://developer.ebay.com/join/api-license-agreement"
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
+ "version": "v1.23.2"
},
- "/ad_campaign/{campaign_id}/bulk_create_ads_by_listing_id": {
- "post": {
- "tags": [
- "ad"
- ],
- "description": "This method adds multiple listings to an existing Promoted Listings campaign using listingId values generated by the Trading API or Inventory API, or using values generated by an ad group ID.For Promoted Listings Standard (PLS) campaigns using the Cost Per Sale (CPS) funding model, bulk ads may be directly created for the listing.
For each listing ID specified in the request, this method:
- Creates an ad for the listing.
- Sets the bid percentage (also known as the ad rate) for the ad.
- Associates the ad with the specified campaign.
To create an ad for a listing, specify its listingId, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Listing IDs are generated by eBay when a seller creates listings with the Trading API.
You can specify a maximum of 500 listings per call and each campaign can have ads for a maximum of 50,000 items. Be aware when using this call that each variation in a multiple-variation listing creates an individual ad.
For Promoted Listings Advanced (PLA) campaigns using the Cost Per Click (CPC) funding model, an ad group must be created first. If no ad group has been created for the campaign, ads cannot be created.
For the ad group specified in the request, this method associates the ad with the specified ad group.
To create an ad for an ad group, specify the name of the ad group plus the defaultBid for the ad in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Ad groups are generated using the createAdGroup method.
You can specify one or more ad groups per campaign.
Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.
",
- "operationId": "bulkCreateAdsByListingId",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that's generated when a campaign is created. Get a seller's campaign IDs by calling getCampaigns.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "The container for the bulk request to create ads for eBay listing IDs. eBay listing IDs are generated by the Trading API and Inventory API when the listing is created on eBay.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The container for the bulk request to create ads for eBay listing IDs. eBay listing IDs are generated by the Trading API and Inventory API when the listing is created on eBay.",
- "$ref": "#/components/schemas/BulkCreateAdRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkAdResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
- },
- "35010": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The bidPercentage should not be provided when selected adRateStrategy is DYNAMIC for the campaign."
- },
- "35013": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID {listingId} is not valid."
- },
- "35014": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing Id is required for this call."
- },
- "35018": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
- },
- "35033": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one request is required for bulk requests."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35036": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "An ad for listing ID {listingId} already exists."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "35048": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID {listingId} is invalid or has ended."
- },
- "35080": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' is not supported for CPC funding model."
- },
- "36106": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'adGroupId' is not supported for CPS funding model."
- },
- "36108": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'adGroupId' is required for CPC funding model."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No ad group found for ad group id {ad_group_id}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35052": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
- },
- "35054": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace."
- },
- "35057": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} does not belong to the seller making this call."
- },
- "35058": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} is not a fixed price item. This is a requirement for a promoted listing."
- },
- "35059": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} is not a multi-quantity item. This is a requirement for a promoted listing."
- },
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35071": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
- },
- "35075": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "36152": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'bidPercentage' is not supported for CPC funding model."
- },
- "36221": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of ads supported in a ad group with this request. Only {maxItemsLimit} ads are allowed per ad group."
+ "servers": [
+ {
+ "url": "https://api.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/marketing/v1"
}
- }
}
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ }
+ ],
+ "paths": {
+ "/ad_campaign/{campaign_id}/bulk_create_ads_by_inventory_reference": {
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method adds multiple listings that are managed with the Inventory API to an existing Promoted Listings campaign.
For general strategy campaigns using the Cost Per Sale (CPS) model, bulk ads may be directly created for the listing.
For each listing specified in the request, this method:
- Creates an ad for the listing.
- Sets the bid percentage (also known as the ad rate) for the ads created.
- Associates the ads created with the specified campaign.
To create ads for a listing, specify their inventoryReferenceId and inventoryReferenceType, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to which you want to associate the ads using the campaign_id path parameter.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.
Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.",
+ "operationId": "bulkCreateAdsByInventoryReference",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to associated the ads being created.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The container for the bulk request to create ads for eBay inventory reference IDs. eBay inventory reference IDs are seller-defined IDs used by theInventory API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The container for the bulk request to create ads for eBay inventory reference IDs. eBay inventory reference IDs are seller-defined IDs used by theInventory API.",
+ "$ref": "#/components/schemas/BulkCreateAdsByInventoryReferenceRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkCreateAdsByInventoryReferenceResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
+ },
+ "35010": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The bidPercentage should not be provided when selected adRateStrategy is DYNAMIC for the campaign."
+ },
+ "35012": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference ID {inventoryReferenceId} is not valid."
+ },
+ "35018": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
+ },
+ "35033": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one request is required for bulk requests."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35040": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36106": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'adGroupId' is not supported for CPS funding model."
+ },
+ "36108": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'adGroupId' is required for CPC funding model."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No adgroup found for adgroup id {ad_group_id}."
+ },
+ "36219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The ad group with ad group id {ad_group_id} has been archived."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35071": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
+ },
+ "35072": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP'."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/bulk_delete_ads_by_inventory_reference": {
- "post": {
- "tags": [
- "ad"
- ],
- "description": "This method works with listings created with the Inventory API.
The method deletes a set of ads, as specified by a list of inventory reference IDs, from the specified campaign. Inventory reference IDs are seller-defined IDs that are used with the Inventory API.
Pass the campaign_id as a path parameter and populate the payload with a list of inventoryReferenceId and inventoryReferenceType pairs that you want to delete.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to get a list of the seller's inventory reference IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
- "operationId": "bulkDeleteAdsByInventoryReference",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that's generated when a campaign is created. Get a seller's campaign IDs by calling getCampaigns.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This request works with listings created via the Inventory API.
The request is to delete a set of ads in bulk, as specified by a list of inventory reference IDs from the specified campaign.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This request works with listings created via the Inventory API.
The request is to delete a set of ads in bulk, as specified by a list of inventory reference IDs from the specified campaign.",
- "$ref": "#/components/schemas/BulkDeleteAdsByInventoryReferenceRequest"
- }
+ "/ad_campaign/{campaign_id}/bulk_create_ads_by_listing_id": {
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method adds multiple listings to an existing Promoted Listings campaign using listingId values generated by the Trading API or Inventory API, or using values generated by an ad group ID.For general strategy campaigns using the Cost Per Sale (CPS) funding model, bulk ads may be directly created for the listing.
For each listing ID specified in the request, this method:
- Creates an ad for the listing.
- Sets the bid percentage (also known as the ad rate) for the ad.
- Associates the ad with the specified campaign.
To create an ad for a listing, specify its listingId, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Listing IDs are generated by eBay when a seller creates listings with the Trading API.
You can specify a maximum of 500 listings per call and each campaign can have ads for a maximum of 50,000 items. Be aware when using this call that each variation in a multiple-variation listing creates an individual ad.
For manual targeting priority strategy campaigns using the Cost Per Click (CPC) funding model, an ad group must be created first. If no ad group has been created for the campaign, ads cannot be created.
Note: Ad groups are not required when adding listings to a smart targeting campaign.
For the ad group specified in the request, this method associates the ad with the specified ad group.
To create an ad for an ad group, specify the name of the ad group plus the defaultBid for the ad in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Ad groups are generated using the createAdGroup method.
You can specify one or more ad groups per campaign.
Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.
",
+ "operationId": "bulkCreateAdsByListingId",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to associated the ads being created.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The container for the bulk request to create ads for eBay listing IDs. eBay listing IDs are generated by the Trading API and Inventory API when the listing is created on eBay.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The container for the bulk request to create ads for eBay listing IDs. eBay listing IDs are generated by the Trading API and Inventory API when the listing is created on eBay.",
+ "$ref": "#/components/schemas/BulkCreateAdRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkAdResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
+ },
+ "35010": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The bidPercentage should not be provided when selected adRateStrategy is DYNAMIC for the campaign."
+ },
+ "35013": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID {listingId} is not valid."
+ },
+ "35014": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing Id is required for this call."
+ },
+ "35018": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
+ },
+ "35033": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one request is required for bulk requests."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35036": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "An ad for listing ID {listingId} already exists."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "35048": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID {listingId} is invalid or has ended."
+ },
+ "35080": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' is not supported for CPC funding model."
+ },
+ "36106": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'adGroupId' is not supported for CPS funding model."
+ },
+ "36108": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'adGroupId' is required for CPC funding model."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ad group found for ad group id {ad_group_id}."
+ },
+ "36412": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Campaigns where the 'campaignTargetingType' is 'SMART' do not support ad groups. Please remove the {adGroupFieldName} and try again."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35052": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
+ },
+ "35054": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace."
+ },
+ "35057": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} does not belong to the seller making this call."
+ },
+ "35058": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} is not a fixed price item. This is a requirement for a promoted listing."
+ },
+ "35059": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} is not a multi-quantity item. This is a requirement for a promoted listing."
+ },
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35068": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing Ids. Only {maxSupportedNumber} listings are supported per call."
+ },
+ "35071": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
+ },
+ "35075": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "36152": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'bidPercentage' is not supported for CPC funding model."
+ },
+ "36221": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of ads supported in a ad group with this request. Only {maxItemsLimit} ads are allowed per ad group."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "required": true
},
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkDeleteAdsByInventoryReferenceResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
- },
- "35012": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference ID {inventoryReferenceId} is not valid."
- },
- "35018": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
- },
- "35033": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one request is required for bulk requests."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35040": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36101": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This functionality is not supported for the CPC funding model."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35071": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
- },
- "35072": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP'"
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign/{campaign_id}/bulk_delete_ads_by_inventory_reference": {
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method works with listings created with the Inventory API.
The method deletes a set of ads, as specified by a list of inventory reference IDs, from the specified campaign. Inventory reference IDs are seller-defined IDs that are used with the Inventory API.
Pass the campaign_id as a path parameter and populate the payload with a list of inventoryReferenceId and inventoryReferenceType pairs that you want to delete.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to get a list of the seller's inventory reference IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
+ "operationId": "bulkDeleteAdsByInventoryReference",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to delete a set of ads.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This request works with listings created via the Inventory API.
The request is to delete a set of ads in bulk, as specified by a list of inventory reference IDs from the specified campaign.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This request works with listings created via the Inventory API.
The request is to delete a set of ads in bulk, as specified by a list of inventory reference IDs from the specified campaign.",
+ "$ref": "#/components/schemas/BulkDeleteAdsByInventoryReferenceRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkDeleteAdsByInventoryReferenceResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
+ },
+ "35012": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference ID {inventoryReferenceId} is not valid."
+ },
+ "35018": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
+ },
+ "35033": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one request is required for bulk requests."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35040": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36101": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This functionality is not supported for the CPC funding model."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35071": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
+ },
+ "35072": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP'"
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/bulk_delete_ads_by_listing_id": {
- "post": {
- "tags": [
- "ad"
- ],
- "description": "This method works with listing IDs created with either the Trading API or the Inventory API.
The method deletes a set of ads, as specified by a list of listingID values from a Promoted Listings campaign. A listing ID value is generated by eBay when a seller creates a listing with either the Trading API and Inventory API.
Pass the campaign_id as a path parameter and populate the payload with the set of listing IDs that you want to delete.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to get a list of the seller's inventory reference IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.
When using the CPC funding model, use the bulkUpdateAdsStatusByListingId method to change the status of ads to ARCHIVED.",
- "operationId": "bulkDeleteAdsByListingId",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that's generated when a campaign is created. Get a seller's campaign IDs by calling getCampaigns.",
- "required": true,
- "schema": {
- "type": "string"
+ "/ad_campaign/{campaign_id}/bulk_delete_ads_by_listing_id": {
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method works with listing IDs created with either the Trading API or the Inventory API.
The method deletes a set of ads, as specified by a list of listingID values from a Promoted Listings campaign. A listing ID value is generated by eBay when a seller creates a listing with either the Trading API and Inventory API.
Pass the campaign_id as a path parameter and populate the payload with the set of listing IDs that you want to delete.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to get a list of the seller's inventory reference IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.
When using the CPC funding model, use the bulkUpdateAdsStatusByListingId method to change the status of ads to ARCHIVED.",
+ "operationId": "bulkDeleteAdsByListingId",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay-assigned identifier of the ad campaign for which to delete a set of ads.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This request object defines the fields for the bulkDeleteAdsByListingId request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This request object defines the fields for the bulkDeleteAdsByListingId request.",
+ "$ref": "#/components/schemas/BulkDeleteAdRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkDeleteAdResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35013": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID {listingId} is not valid."
+ },
+ "35014": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID is required for this call."
+ },
+ "35018": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
+ },
+ "35033": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one request is required for bulk requests."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35040": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36101": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This functionality is not supported for the CPC funding model."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35071": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This request object defines the fields for the bulkDeleteAdsByListingId request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This request object defines the fields for the bulkDeleteAdsByListingId request.",
- "$ref": "#/components/schemas/BulkDeleteAdRequest"
- }
- }
- },
- "required": true
},
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkDeleteAdResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35013": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID {listingId} is not valid."
- },
- "35014": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID is required for this call."
- },
- "35018": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
- },
- "35033": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one request is required for bulk requests."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35040": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36101": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This functionality is not supported for the CPC funding model."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35071": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign/{campaign_id}/bulk_update_ads_bid_by_inventory_reference": {
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method works with listings created with either the Trading API or the Inventory API. The method updates the bidPercentage values for a set of ads associated with the specified campaign.
Specify the campaign_id as a path parameter and supply a set of listing IDs with their associated updated bidPercentage values in the request body. An eBay listing ID is generated when a listing is created with the Trading API.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to get a list of the seller's inventory reference IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
+ "operationId": "bulkUpdateAdsBidByInventoryReference",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to update the bid percentage for a set of ads.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This request object defines the fields for the BulkCreateAdsByInventoryReference request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This request object defines the fields for the BulkCreateAdsByInventoryReference request.",
+ "$ref": "#/components/schemas/BulkCreateAdsByInventoryReferenceRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkUpdateAdsByInventoryReferenceResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
+ },
+ "35012": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference ID {inventoryReferenceId} is not valid."
+ },
+ "35018": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
+ },
+ "35033": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one request is required for bulk requests."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35040": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36101": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This functionality is not supported for the CPC funding model."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35071": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
+ },
+ "35072": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP'"
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35113": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is not supported when selected adRateStratergy is DYNAMIC for the campaign."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/bulk_update_ads_bid_by_inventory_reference": {
- "post": {
- "tags": [
- "ad"
- ],
- "description": "This method works with listings created with either the Trading API or the Inventory API. The method updates the bidPercentage values for a set of ads associated with the specified campaign.
Specify the campaign_id as a path parameter and supply a set of listing IDs with their associated updated bidPercentage values in the request body. An eBay listing ID is generated when a listing is created with the Trading API.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to get a list of the seller's inventory reference IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
- "operationId": "bulkUpdateAdsBidByInventoryReference",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that's generated when a campaign is created. Get a seller's campaign IDs by calling getCampaigns.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This request object defines the fields for the BulkCreateAdsByInventoryReference request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This request object defines the fields for the BulkCreateAdsByInventoryReference request.",
- "$ref": "#/components/schemas/BulkCreateAdsByInventoryReferenceRequest"
- }
+ "/ad_campaign/{campaign_id}/bulk_update_ads_bid_by_listing_id": {
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method works with listings created with either the Trading API or the Inventory API. The method updates the bidPercentage values for a set of ads associated with the specified campaign.
Specify the campaign_id as a path parameter and supply a set of listing IDs with their associated updated bidPercentage values in the request body. An eBay listing ID is generated when a listing is created with the Trading API.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to get a list of the seller's inventory reference IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
+ "operationId": "bulkUpdateAdsBidByListingId",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to update the bid percentage for a set of ads.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This request object defines the fields for the BulkCreateAdsByListingId request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This request object defines the fields for the BulkCreateAdsByListingId request.",
+ "$ref": "#/components/schemas/BulkCreateAdRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkAdUpdateResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
+ },
+ "35013": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID {listingId} is not valid."
+ },
+ "35014": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing Id is required for this call."
+ },
+ "35018": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
+ },
+ "35033": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one request is required for bulk requests."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35044": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "35048": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID {listingId} is invalid or has ended."
+ },
+ "36101": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This functionality is not supported for the CPC funding model."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35052": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
+ },
+ "35058": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} is not a fixed price item. This is a requirement for a promoted listing."
+ },
+ "35059": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} is not a multi-quantity item. This is a requirement for a promoted listing."
+ },
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35071": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
+ },
+ "35075": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35113": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is not supported when selected adRateStratergy is DYNAMIC for the campaign."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "required": true
},
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkUpdateAdsByInventoryReferenceResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
- },
- "35012": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference ID {inventoryReferenceId} is not valid."
- },
- "35018": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
- },
- "35033": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one request is required for bulk requests."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35040": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36101": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This functionality is not supported for the CPC funding model."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35071": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
- },
- "35072": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP'"
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "35113": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is not supported when selected adRateStratergy is DYNAMIC for the campaign."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign/{campaign_id}/bulk_update_ads_status": {
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "Note: This method is only available for select partners who have been approved for the priority strategy program. For information about how to request access to this program, refer to Priority Strategy Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for priority strategy, use the getAdvertisingEligibility method in Account API.
This method works with listings created with either the Trading API or the Inventory API.
This method updates the status of ads in bulk.
Specify the campaign_id you want to update as a URI parameter, and configure the adGroupStatus in the request payload.",
+ "operationId": "bulkUpdateAdsStatus",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad statuses being updated.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The bulk request to update the ads.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The bulk request to update the ads.",
+ "$ref": "#/components/schemas/BulkUpdateAdStatusRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkAdUpdateStatusResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35033": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one request is required for bulk requests."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35044": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "35083": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The requested 'adStatus' is not valid."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35052": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
+ },
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35071": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing Ids or inventory reference Ids. Only {maxSupportedNumber} Ids are supported per call."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "36160": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This functionality is only supported for CPC funding model."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/bulk_update_ads_bid_by_listing_id": {
- "post": {
- "tags": [
- "ad"
- ],
- "description": "This method works with listings created with either the Trading API or the Inventory API. The method updates the bidPercentage values for a set of ads associated with the specified campaign.
Specify the campaign_id as a path parameter and supply a set of listing IDs with their associated updated bidPercentage values in the request body. An eBay listing ID is generated when a listing is created with the Trading API.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to get a list of the seller's inventory reference IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
- "operationId": "bulkUpdateAdsBidByListingId",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that's generated when a campaign is created. Get a seller's campaign IDs by calling getCampaigns.",
- "required": true,
- "schema": {
- "type": "string"
+ "/ad_campaign/{campaign_id}/bulk_update_ads_status_by_listing_id": {
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "The method updates the status of ads in bulk, based on listing ID values.
Specify the campaign_id as a path parameter and supply a set of listing IDs with their updated adStatus values in the request body. An eBay listing ID is generated when a listing is created with the Trading API.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to retrieve a list of seller inventory reference IDs.",
+ "operationId": "bulkUpdateAdsStatusByListingId",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ads being updated.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The bulk request to update ads.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The bulk request to update ads.",
+ "$ref": "#/components/schemas/BulkUpdateAdStatusByListingIdRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkAdUpdateStatusByListingIdResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35013": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing Id {listingId} is not valid."
+ },
+ "35014": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing Id is required for this call."
+ },
+ "35018": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "There are duplicate listing Ids or inventoryReference Ids in this request. You must remove the duplicate."
+ },
+ "35033": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one request is required for bulk requests."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "35048": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing Id {listingId} is invalid or has ended."
+ },
+ "35083": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The requested 'adStatus' is not valid."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ad group found for ad group id {ad_group_id}."
+ },
+ "36219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The ad group with ad group id {ad_group_id} has been archived."
+ },
+ "36412": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Campaigns where the 'campaignTargetingType' is 'SMART' do not support ad groups. Please remove the {adGroupFieldName} and try again."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35052": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
+ },
+ "35058": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing Id {listingId} is not a fixed price item. This is a requirement for a promoted listing."
+ },
+ "35059": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing Id {listingId} is not a multi-quantity item. This is a requirement for a promoted listing."
+ },
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35071": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing Ids or inventory reference Ids. Only {maxSupportedNumber} Ids are supported per call."
+ },
+ "35075": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35084": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The Ad associated with listing Id {listingId} is archived."
+ },
+ "35085": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adGroupId' {ad_group_id} does not exist under campaign {campaign_id}."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This request object defines the fields for the BulkCreateAdsByListingId request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This request object defines the fields for the BulkCreateAdsByListingId request.",
- "$ref": "#/components/schemas/BulkCreateAdRequest"
- }
- }
- },
- "required": true
},
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkAdUpdateResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
- },
- "35013": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID {listingId} is not valid."
- },
- "35014": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing Id is required for this call."
- },
- "35018": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate."
- },
- "35033": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one request is required for bulk requests."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35044": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "35048": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID {listingId} is invalid or has ended."
- },
- "36101": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This functionality is not supported for the CPC funding model."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35052": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
- },
- "35058": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} is not a fixed price item. This is a requirement for a promoted listing."
- },
- "35059": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} is not a multi-quantity item. This is a requirement for a promoted listing."
- },
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35071": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call."
- },
- "35075": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "35113": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is not supported when selected adRateStratergy is DYNAMIC for the campaign."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign/{campaign_id}/ad": {
+ "get": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method retrieves Promoted Listings ads that are associated with listings created with either the Trading API or the Inventory API. The method retrieves ads related to the specified campaign. Specify the Promoted Listings campaign to target with the campaign_id path parameter.
Because of the large number of possible results, you can use query parameters to paginate the result set by specifying a limit, which dictates how many ads to return on each page of the response. You can also specify how many ads to skip in the result set before returning the first result using the offset path parameter.
Call getCampaigns to retrieve the current campaign IDs for the seller.
",
+ "operationId": "getAds",
+ "parameters": [
+ {
+ "name": "ad_group_ids",
+ "in": "query",
+ "description": "A comma-separated list of ad group IDs. The results will be filtered to only include active ads for these ad groups.
Use the getAdGroups method to retrieve the ad group ID for the ad group.
Note: This field only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "ad_status",
+ "in": "query",
+ "description": "A comma-separated list of ad statuses. The results will be filtered to only include the given statuses of the ad. If none are provided, all ads are returned.
See AdStatusEnum for supported values.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ads being retrieved.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "Specifies the maximum number of ads to return on a page in the paginated response.
Default: 10
Maximum: 500",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "listing_ids",
+ "in": "query",
+ "description": "A comma-separated list of listing IDs.
Note: The response includes only active ads. The results do not include listing IDs that are excluded by other conditions.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "Specifies the number of ads to skip in the result set before returning the first ad in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AdPagedCollectionResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35013": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID {listingId} is not valid."
+ },
+ "35029": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
+ },
+ "35030": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'offset' cannot be less than zero."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "35083": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The requested 'adStatus' is not valid."
+ },
+ "36106": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'ad_group_ids' is not supported for CPS funding model."
+ },
+ "36412": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Campaigns where the 'campaignTargetingType' is 'SMART' do not support ad groups. Please remove the {adGroupFieldName} and try again."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35068": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing IDs. Only {maxSupportedNumber} listings are supported per call."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method adds a listing to an existing Promoted Listings campaign using a listingId value generated by the Trading API or Inventory API, or using a value generated by an ad group ID. For general strategy campaigns using the Cost Per Sale (CPS) funding model, an ad may be directly created for the listing.
For the listing ID specified in the request, this method:
- Creates an ad for the listing.
- Sets the bid percentage (also known as the ad rate) for the ad.
- Associates the ad with the specified campaign.
To create an ad for a listing, specify its listingId, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to associate the ad with using the campaign_id path parameter. Listing IDs are generated by eBay when a seller creates listings with the Trading API.
For manual targeting priority strategy campaigns using the Cost Per Click (CPC) funding model, an ad group must be created first. If no ad group has been created for the campaign, ads cannot be created.
Note: Ad groups are not required when adding listings to a smart targeting campaign.
For the ad group specified in the request, this method associates the ad with the specified ad group.
To create an ad for an ad group, specify the name of the ad group in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Ad groups are generated using the createAdGroup method.
You can specify one or more ad groups per campaign.
Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.
This call has no response payload. If the ad is successfully created, a 201 Created HTTP status code and the getAd URI of the ad are returned in the location header.
",
+ "operationId": "createAdByListingId",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to associate the newly created ad.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This request object defines the fields used in the createAdByListingId request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This request object defines the fields used in the createAdByListingId request.",
+ "$ref": "#/components/schemas/CreateAdRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "201": {
+ "description": "Created",
+ "headers": {
+ "Location": {
+ "schema": {
+ "type": "string",
+ "description": "The location response header contains the getAd URI of the newly created ad. The URI includes the newly created adID, which you can use to reference the ad."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
+ },
+ "35010": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The bidPercentage should not be provided when selected adRateStrategy is DYNAMIC for the campaign."
+ },
+ "35013": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID {listingId} is not valid."
+ },
+ "35014": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID is required for this call."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35036": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "An ad for listing ID {listingId} already exists."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "35048": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID {listingId} is invalid or has ended."
+ },
+ "35080": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' is not supported for CPC funding model."
+ },
+ "36106": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'adGroupId' {adGroupId} is not supported for CPS funding model."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No adgroup found for adgroup id {ad_group_id}."
+ },
+ "36219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The ad group with ad_group id {ad_group_id} has been archived."
+ },
+ "36412": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Campaigns where the 'campaignTargetingType' is 'SMART' do not support ad groups. Please remove the {adGroupFieldName} and try again."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35052": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
+ },
+ "35054": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace."
+ },
+ "35057": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} does not belong to the seller making this call."
+ },
+ "35058": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} is not a fixed price item. This is a requirement for a promoted listing."
+ },
+ "35059": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} is not a multi-quantity item. This is a requirement for a promoted listing."
+ },
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35075": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "36221": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of ads supported in a ad group with this request. Only {maxItemsLimit} ads are allowed per ad group."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/bulk_update_ads_status": {
- "post": {
- "tags": [
- "ad"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method works with listings created with either the Trading API or the Inventory API.
This method updates the status of ads in bulk.
Specify the campaign_id you want to update as a URI parameter, and configure the adGroupStatus in the request payload.",
- "operationId": "bulkUpdateAdsStatus",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
+ "/ad_campaign/{campaign_id}/create_ads_by_inventory_reference": {
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method adds a listing that is managed with the Inventory API to an existing Promoted Listings campaign.
For general strategy campaigns using the Cost Per Sale (CPS) funding model, an ad may be directly created for the listing.
For each listing specified in the request, this method:
- Creates an ad for the listing.
- Sets the bid percentage (also known as the ad rate) for the ads created.
- Associates the created ad with the specified campaign.
To create an ad for a listing, specify its inventoryReferenceId and inventoryReferenceType, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to associate the ad with using the campaign_id path parameter.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.
Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.",
+ "operationId": "createAdsByInventoryReference",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to associate the newly created ads.
Use the getCampaigns method to retrieve campaign IDs",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This request object defines the fields used in the createAdsByInventoryReference request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This request object defines the fields used in the createAdsByInventoryReference request.",
+ "$ref": "#/components/schemas/CreateAdsByInventoryReferenceRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "201": {
+ "description": "Created",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AdReferences"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
+ },
+ "35010": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The bidPercentage should not be provided when selected adRateStrategy is DYNAMIC for the campaign."
+ },
+ "35012": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference ID {inventoryReferenceId} is not valid."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35040": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "35080": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' is not supported for CPC funding model"
+ },
+ "36106": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'adGroupId' is not supported for CPS funding model."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ad group found for ad group id {ad_group_id}."
+ },
+ "36219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The ad group with ad group id {ad_group_id} has been archived."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35072": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP'"
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
- ],
- "requestBody": {
- "description": "The bulk request to update the ads.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The bulk request to update the ads.",
- "$ref": "#/components/schemas/BulkUpdateAdStatusRequest"
- }
- }
- },
- "required": true
},
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkAdUpdateStatusResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35033": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one request is required for bulk requests."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35044": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "35083": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The requested 'adStatus' is not valid."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35052": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
- },
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35071": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of listing Ids or inventory reference Ids. Only {maxSupportedNumber} Ids are supported per call."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "36160": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This functionality is only supported for CPC funding model."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign/{campaign_id}/ad/{ad_id}": {
+ "get": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method retrieves the specified ad from the specified campaign. In the request, supply the campaign_id and ad_id as path parameters.
Call getCampaigns to retrieve a list of the seller's current campaign IDs and call getAds to retrieve their current ad IDs.
",
+ "operationId": "getAd",
+ "parameters": [
+ {
+ "name": "ad_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the ad being retrieved.
Use the getAds method to retrieve ad IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad being retrieved.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Ad"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35044": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Business error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "delete": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method removes the specified ad from the specified campaign.
Pass the ID of the ad to delete with the ID of the campaign associated with the ad as path parameters to the call.
Call getCampaigns to get the current list of the seller's campaign IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.
When using the CPC funding model, use the bulkUpdateAdsStatusByListingId method to change the status of ads to ARCHIVED.",
+ "operationId": "deleteAd",
+ "parameters": [
+ {
+ "name": "ad_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the ad being deleted.
Use the getAds method to retrieve ad IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad being deleted.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35044": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36101": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This functionality is not supported for the CPC funding model."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/bulk_update_ads_status_by_listing_id": {
- "post": {
- "tags": [
- "ad"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method works with listings created with either the Trading API or the Inventory API.
The method updates the status of ads in bulk, based on listing ID values.
Specify the campaign_id as a path parameter and supply a set of listing IDs with their updated adStatus values in the request body. An eBay listing ID is generated when a listing is created with the Trading API.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to retrieve a list of seller inventory reference IDs.",
- "operationId": "bulkUpdateAdsStatusByListingId",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "The bulk request to update ads.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The bulk request to update ads.",
- "$ref": "#/components/schemas/BulkUpdateAdStatusByListingIdRequest"
- }
+ "/ad_campaign/{campaign_id}/delete_ads_by_inventory_reference": {
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method works with listings that are managed with the Inventory API. The method deletes ads using a list of seller-defined inventory reference IDs, used with the Inventory API, that are associated with the specified campaign ID.
Specify the campaign ID (as a path parameter) and a list of inventoryReferenceId and inventoryReferenceType pairs to be deleted.
Call getCampaigns to get a list of the seller's current campaign IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.
When using the CPC funding model, use the bulkUpdateAdsStatusByInventoryReference method to change the status of ads to ARCHIVED.",
+ "operationId": "deleteAdsByInventoryReference",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ads being deleted.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This request object defines the fields for the deleteAdsByInventoryReference request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This request object defines the fields for the deleteAdsByInventoryReference request.",
+ "$ref": "#/components/schemas/DeleteAdsByInventoryReferenceRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AdIds"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35012": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference ID {inventoryReferenceId} is not valid."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35040": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36101": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This functionality is not supported for the CPC funding model."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35072": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the inventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP'"
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "required": true
},
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkAdUpdateStatusByListingIdResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35013": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing Id {listingId} is not valid."
- },
- "35014": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing Id is required for this call."
- },
- "35018": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "There are duplicate listing Ids or inventoryReference Ids in this request. You must remove the duplicate."
- },
- "35033": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one request is required for bulk requests."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "35048": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing Id {listingId} is invalid or has ended."
- },
- "35083": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The requested 'adStatus' is not valid."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No ad group found for ad group id {ad_group_id}."
- },
- "36219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The ad group with ad group id {ad_group_id} has been archived."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35052": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
- },
- "35058": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing Id {listingId} is not a fixed price item. This is a requirement for a promoted listing."
- },
- "35059": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing Id {listingId} is not a multi-quantity item. This is a requirement for a promoted listing."
- },
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35071": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of listing Ids or inventory reference Ids. Only {maxSupportedNumber} Ids are supported per call."
- },
- "35075": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35084": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The Ad associated with listing Id {listingId} is archived."
- },
- "35085": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'adGroupId' {ad_group_id} does not exist under campaign {campaign_id}."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign/{campaign_id}/get_ads_by_inventory_reference": {
+ "get": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method retrieves Promoted Listings ads associated with listings that are managed with the Inventory API from the specified campaign.
Supply the campaign_id as a path parameter and use query parameters to specify the inventory_reference_id and inventory_reference_type pairs.
In the Inventory API, an inventory reference ID is either a seller-defined SKU value or an inventoryItemGroupKey (a seller-defined ID for an inventory item group, which is an entity that's used in the Inventory API to create a multiple-variation listing). To indicate a listing managed by the Inventory API, you must always specify both an inventory_reference_id and the associated inventory_reference_type.
Call getCampaigns to retrieve all of the seller's the current campaign IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
+ "operationId": "getAdsByInventoryReference",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ads being retrieved.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "inventory_reference_id",
+ "in": "query",
+ "description": "This query parameter specifies the unique identifier of a single-item listing or a multi-variation listing.
To retrieve an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).
To retrieve an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "inventory_reference_type",
+ "in": "query",
+ "description": "This query parameter specifies the type of the item the inventory_reference_id references.
See InventoryReferenceType for supported values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Ads"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35012": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference ID {inventoryReferenceId} is not valid."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35040": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36106": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'adGroupId' is not supported for CPS funding model."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/ad": {
- "get": {
- "tags": [
- "ad"
- ],
- "description": "This method retrieves Promoted Listings ads that are associated with listings created with either the Trading API or the Inventory API. The method retrieves ads related to the specified campaign. Specify the Promoted Listings campaign to target with the campaign_id path parameter.
Because of the large number of possible results, you can use query parameters to paginate the result set by specifying a limit, which dictates how many ads to return on each page of the response. You can also specify how many ads to skip in the result set before returning the first result using the offset path parameter.
Call getCampaigns to retrieve the current campaign IDs for the seller.
",
- "operationId": "getAds",
- "parameters": [
- {
- "name": "ad_group_ids",
- "in": "query",
- "description": "A comma-separated list of ad group IDs. The results will be filtered to only include active ads for these ad groups. Call getAdGroups to retrieve the ad group ID for the ad group.
Note: This field only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "ad_status",
- "in": "query",
- "description": "A comma-separated list of ad statuses. The results will be filtered to only include the given statuses of the ad. If none are provided, all ads are returned.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "limit",
- "in": "query",
- "description": "Specifies the maximum number of ads to return on a page in the paginated response. Default: 10
Maximum: 500
",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "listing_ids",
- "in": "query",
- "description": "A comma-separated list of listing IDs. The response includes only active ads (ads associated with a RUNNING campaign). The results do not include listing IDs that are excluded by other conditions.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "Specifies the number of ads to skip in the result set before returning the first ad in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/AdPagedCollectionResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35013": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID {listingId} is not valid."
- },
- "35029": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
- },
- "35030": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'offset' cannot be less than zero."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "35083": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The requested 'adStatus' is not valid."
- },
- "36106": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'ad_group_ids' is not supported for CPS funding model."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35068": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of listing IDs. Only {maxSupportedNumber} listings are supported per call."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign/{campaign_id}/ad/{ad_id}/update_bid": {
+ "post": {
+ "tags": [
+ "ad"
+ ],
+ "description": "This method updates the bid percentage (also known as the \"ad rate\") for the specified ad in the specified campaign. In the request, supply the campaign_id and ad_id as path parameters, and supply the new bidPercentage value in the payload of the call.
Call getCampaigns to retrieve a seller's current campaign IDs and call getAds to get their ad IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
+ "operationId": "updateBid",
+ "parameters": [
+ {
+ "name": "ad_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the ad for which the bid percentage is being updated.
Use the getAds method to retrieve ad IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad being updated.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the fields for the updateBid request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields for the updateBid request.",
+ "$ref": "#/components/schemas/UpdateBidPercentageRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "No content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35044": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "35048": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID {listingId} is invalid or has ended."
+ },
+ "36101": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This functionality is not supported for the CPC funding model."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35052": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
+ },
+ "35058": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} is not a fixed price item. This is a requirement for a promoted listing."
+ },
+ "35059": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing ID {listingId} is not a multi-quantity item. This is a requirement for a promoted listing."
+ },
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35064": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for key based campaigns."
+ },
+ "35075": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35113": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is not supported when selected adRateStratergy is DYNAMIC for the campaign."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "post": {
- "tags": [
- "ad"
- ],
- "description": "This method adds a listing to an existing Promoted Listings campaign using a listingId value generated by the Trading API or Inventory API, or using a value generated by an ad group ID. For Promoted Listings Standard (PLS) campaigns using the Cost Per Sale (CPS) funding model, an ad may be directly created for the listing.
For the listing ID specified in the request, this method:
- Creates an ad for the listing.
- Sets the bid percentage (also known as the ad rate) for the ad.
- Associates the ad with the specified campaign.
To create an ad for a listing, specify its listingId, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to associate the ad with using the campaign_id path parameter. Listing IDs are generated by eBay when a seller creates listings with the Trading API.
For Promoted Listings Advanced (PLA) campaigns using the Cost Per Click (CPC) funding model, an ad group must be created first. If no ad group has been created for the campaign, an ad cannot be created.
For the ad group specified in the request, this method associates the ad with the specified ad group.
To create an ad for an ad group, specify the name of the ad group in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Ad groups are generated using the createAdGroup method.
You can specify one or more ad groups per campaign.
Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.
This call has no response payload. If the ad is successfully created, a 201 Created HTTP status code and the getAd URI of the ad are returned in the location header.
",
- "operationId": "createAdByListingId",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This request object defines the fields used in the createAdByListingId request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This request object defines the fields used in the createAdByListingId request.",
- "$ref": "#/components/schemas/CreateAdRequest"
- }
+ "/ad_campaign/{campaign_id}/ad_group": {
+ "get": {
+ "tags": [
+ "ad_group"
+ ],
+ "description": "This method retrieves ad groups for the specified campaigns.
Each campaign can only have one ad group.
In the request, supply the campaign_ids as path parameters.
Call getCampaigns to retrieve a list of the current campaign IDs for a seller.",
+ "operationId": "getAdGroups",
+ "parameters": [
+ {
+ "name": "ad_group_status",
+ "in": "query",
+ "description": "A comma-separated list of ad group statuses. The results will be filtered to only include the given statuses of the ad group.
See AdGroupStatusEnum for supported values.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad groups being retrieved.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The number of results, from the current result set, to be returned in a single page.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "The number of results that will be skipped in the result set. This is used with the limit field to control the pagination of the output.
For example, if the offset is set to 0 and the limit is set to 10, the method will retrieve items 1 through 10 from the list of items returned. If the offset is set to 10 and the limit is set to 10, the method will retrieve items 11 through 20 from the list of items returned.
Default: 0",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AdGroupPagedCollectionResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35029": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
+ },
+ "35030": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'offset' cannot be less than zero."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "post": {
+ "tags": [
+ "ad_group"
+ ],
+ "description": "This method adds an ad group to an existing priority strategy campaign that uses manual targeting.
To create an ad group for a campaign, specify the defaultBid for the ad group in the payload of the request. Then specify the campaign to which the ad group should be associated using the campaign_id path parameter.
Each campaign can have one or more associated ad groups.",
+ "operationId": "createAdGroup",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign to associate with the ad group being created.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the fields for the createAdGroup request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields for the createAdGroup request.",
+ "$ref": "#/components/schemas/CreateAdGroupRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "201": {
+ "description": "Created",
+ "headers": {
+ "Location": {
+ "schema": {
+ "type": "string",
+ "description": "The location response header contains the getAdGroup URL to the newly created ad group. The URL includes the newly assigned adGroupID, which you can use to retrieve the ad group."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36201": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "An ad group with name {name} already exists for this campaign."
+ },
+ "36202": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The ad group name cannot be more than {maxAdGroupNameLength} characters."
+ },
+ "36203": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' value {defaultBidValue} is not valid. The default bid value should be a double precision value."
+ },
+ "36204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' currency {defaultBidCurrency} is not valid or missing."
+ },
+ "36205": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' value {defaultBidValue} is below floor value {bidFloorValue}."
+ },
+ "36206": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' value {defaultBidValue} is above max value {bidMaxValue}."
+ },
+ "36207": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' value {defaultBidValue} is more than daily budget."
+ },
+ "36212": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' currency {defaultBidCurrency} should be the same as the daily budget."
+ },
+ "36214": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Ad Group name is required for this call."
+ },
+ "36215": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' is required for this call."
+ },
+ "36216": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' value is required for this call."
+ },
+ "36217": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The Ad Group name contains invalid characters. {notAllowedCharacters} are not allowed."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ },
+ "36213": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign funding model should be CPC. Please check funding model for provided campaign id."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "required": true
},
- "responses": {
- "201": {
- "description": "Created",
- "headers": {
- "Location": {
- "schema": {
- "type": "string",
- "description": "The location response header contains the getAd URI of the newly created ad. The URI includes the newly created adID, which you can use to reference the ad."
- }
- }
+ "/ad_campaign/{campaign_id}/ad_group/{ad_group_id}": {
+ "get": {
+ "tags": [
+ "ad_group"
+ ],
+ "description": "This method retrieves the details of a specified ad group, such as the ad groupās default bid and status.
In the request, specify the campaign_id and ad_group_id as path parameters.
Call getCampaigns to retrieve a list of the current campaign IDs for a seller and call getAdGroups for the ad group ID of the ad group you wish to retrieve.",
+ "operationId": "getAdGroup",
+ "parameters": [
+ {
+ "name": "ad_group_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the ad group being retrieved.
Use the getAdGroups method to retrieve ad group IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad group being retrieved.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AdGroup"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ad group found for ad group id {ad_group_id}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ },
+ "36213": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign funding model should be CPC. Please check funding model for provided campaign id."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
},
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
- },
- "35010": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The bidPercentage should not be provided when selected adRateStrategy is DYNAMIC for the campaign."
- },
- "35013": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID {listingId} is not valid."
- },
- "35014": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID is required for this call."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35036": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "An ad for listing ID {listingId} already exists."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "35048": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID {listingId} is invalid or has ended."
- },
- "35080": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' is not supported for CPC funding model."
- },
- "36106": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'adGroupId' {adGroupId} is not supported for CPS funding model."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No adgroup found for adgroup id {ad_group_id}."
- },
- "36219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The ad group with ad_group id {ad_group_id} has been archived."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35052": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
- },
- "35054": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace."
- },
- "35057": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} does not belong to the seller making this call."
- },
- "35058": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} is not a fixed price item. This is a requirement for a promoted listing."
- },
- "35059": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} is not a multi-quantity item. This is a requirement for a promoted listing."
- },
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35075": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "36221": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of ads supported in a ad group with this request. Only {maxItemsLimit} ads are allowed per ad group."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "put": {
+ "tags": [
+ "ad_group"
+ ],
+ "description": "This method updates the ad group associated with a campaign.
With this method, you can modify the default bid for the ad group, change the state of the ad group, or change the name of the ad group. Pass the ad_group_id you want to update as a URI parameter, and configure the adGroupStatus and defaultBid in the request payload.
Call getAdGroup to retrieve the current default bid and status of the ad group that you would like to update.",
+ "operationId": "updateAdGroup",
+ "parameters": [
+ {
+ "name": "ad_group_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the ad group that is being updated.
Use the getAdGroups method to retrieve ad group IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which the ad group is being updated.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the fields for the UpdateAdGroup request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields for the UpdateAdGroup request.",
+ "$ref": "#/components/schemas/UpdateAdGroupRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36201": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "An ad group with name {name} already exists for this campaign."
+ },
+ "36202": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The ad group name cannot be more than {maxAdGroupNameLength} characters."
+ },
+ "36203": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' value {defaultBidValue} is not valid. The default bid value should be a double precision value."
+ },
+ "36204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' currency {defaultBidCurrency} is not valid or missing."
+ },
+ "36205": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' value {defaultBidValue} is below floor value {bidFloorValue}."
+ },
+ "36206": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' value {defaultBidValue} is above max value {bidMaxValue}."
+ },
+ "36207": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' value {defaultBidValue} is more than daily budget."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ad group found for ad group id {ad_group_id}."
+ },
+ "36212": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' currency {defaultBidCurrency} should be the same as the daily budget."
+ },
+ "36216": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' value {defaultBidValue} is not valid or missing."
+ },
+ "36217": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The Ad Group name contains invalid characters. {notAllowedCharacters} are not allowed."
+ },
+ "36224": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'defaultBid' or 'adGroupStatus' or 'name' value is required for this call."
+ },
+ "36225": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'ad_group_statuses' value is invalid. It should be either ACTIVE, PAUSED or ARCHIVED."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ },
+ "36213": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign funding model should be CPC. Please check funding model for provided campaign id."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/create_ads_by_inventory_reference": {
- "post": {
- "tags": [
- "ad"
- ],
- "description": "This method adds a listing that is managed with the Inventory API to an existing Promoted Listings campaign.
For Promoted Listings Standard (PLS) campaigns using the Cost Per Sale (CPS) funding model, an ad may be directly created for the listing.
For each listing specified in the request, this method:
- Creates an ad for the listing.
- Sets the bid percentage (also known as the ad rate) for the ads created.
- Associates the created ad with the specified campaign.
To create an ad for a listing, specify its inventoryReferenceId and inventoryReferenceType, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to associate the ad with using the campaign_id path parameter.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.
Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.",
- "operationId": "createAdsByInventoryReference",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
+ "/ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_bids": {
+ "post": {
+ "tags": [
+ "ad_group"
+ ],
+ "description": "This method allows sellers to retrieve the suggested bids for input keywords and match type.",
+ "operationId": "suggestBids",
+ "parameters": [
+ {
+ "name": "ad_group_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the ad group containing the keywords for which the bid suggestions will be provided.
Use the getAdGroups method to retrieve ad group IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the keywords for which bid suggestions will be provided.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The data requested to retrieve the suggested bids.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The data requested to retrieve the suggested bids.",
+ "$ref": "#/components/schemas/TargetedBidRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/TargetedBidsPagedCollection"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35041": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'marketplaceId' is required."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "35091": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You have exceeded the maximum number of requests. Only {maxSupportedNumber} are supported per call."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ad group found for ad group id {ad_group_id}."
+ },
+ "36301": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The provided keyword match type is not supported. Valid values are: {matchTypeValues}."
+ },
+ "36304": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keywordText {keywordText} cannot be more than {maxKeywordTextLength} characters."
+ },
+ "36311": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keywordText cannot be null or empty."
+ },
+ "36312": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keywordText contains invalid characters {invalidCharacters}"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35051": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}."
+ },
+ "36320": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The keywordText {keywordText} cannot have total number of words more than {maxWordsInKeyword} words"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
- ],
- "requestBody": {
- "description": "This request object defines the fields used in the createAdsByInventoryReference request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This request object defines the fields used in the createAdsByInventoryReference request.",
- "$ref": "#/components/schemas/CreateAdsByInventoryReferenceRequest"
- }
- }
- },
- "required": true
},
- "responses": {
- "201": {
- "description": "Created",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/AdReferences"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
- },
- "35010": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The bidPercentage should not be provided when selected adRateStrategy is DYNAMIC for the campaign."
- },
- "35012": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference ID {inventoryReferenceId} is not valid."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35040": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "35080": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' is not supported for CPC funding model"
- },
- "36106": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'adGroupId' is not supported for CPS funding model."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No ad group found for ad group id {ad_group_id}."
- },
- "36219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The ad group with ad group id {ad_group_id} has been archived."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35072": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP'"
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
+ "/ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_keywords": {
+ "post": {
+ "tags": [
+ "ad_group"
+ ],
+ "description": "This method allows sellers to retrieve a list of keyword ideas to be targeted for Promoted Listings campaigns.",
+ "operationId": "suggestKeywords",
+ "parameters": [
+ {
+ "name": "ad_group_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the ad group for which the keyword suggestions will be provided.
Use the getAdGroups method to retrieve ad group IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which keyword suggestions will be provided.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The required data to retrieve suggested keywords.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The required data to retrieve suggested keywords.",
+ "$ref": "#/components/schemas/TargetedKeywordRequest"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/TargetedKeywordsPagedCollection"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35013": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing Id {listingId} is not valid."
+ },
+ "35041": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'marketplaceId' is required."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ad group found for ad group id {ad_group_id}."
+ },
+ "36301": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The provided keyword match type is not supported. Valid values are: {matchTypeValues}."
+ },
+ "70006": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The provided exclusion is not supported. Valid values are {supportedExclusions}."
+ },
+ "70007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The provided additionalInfo is not supported. Valid values are {supportedAdditionalInfo}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35051": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}."
+ },
+ "35054": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing Id {listingId} was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace."
+ },
+ "35057": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing Id {listingId} does not belong to the seller making this call."
+ },
+ "35068": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing Ids. Only {maxSupportedNumber} listings are supported per call."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/ad/{ad_id}": {
- "get": {
- "tags": [
- "ad"
- ],
- "description": "This method retrieves the specified ad from the specified campaign. In the request, supply the campaign_id and ad_id as path parameters.
Call getCampaigns to retrieve a list of the seller's current campaign IDs and call getAds to retrieve their current ad IDs.
",
- "operationId": "getAd",
- "parameters": [
- {
- "name": "ad_id",
- "in": "path",
- "description": "A unique identifier for an ad. This ID is generated when the ad is created.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Ad"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35044": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- }
- }
+ "/ad_campaign/{campaign_id}/clone": {
+ "post": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method clones (makes a copy of) the specified campaign's campaign criterion. The campaign criterion is a container for the fields that define the criteria for a rule-based campaign.To clone a campaign, supply the campaign_id as a path parameter in your call. There is no request payload.
The ID of the newly-cloned campaign is returned in the Location response header.
Call getCampaigns to retrieve a seller's current campaign IDs.
Requirement: In order to clone a campaign, the campaignStatus must be ENDED and the campaign must define a set of selection rules (it must be a rules-based campaign).
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
+ "operationId": "cloneCampaign",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign being cloned.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the fields for a clone campaign request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields for a clone campaign request.",
+ "$ref": "#/components/schemas/CloneCampaignRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "201": {
+ "description": "Success",
+ "headers": {
+ "Location": {
+ "schema": {
+ "type": "string",
+ "description": "The location response header contains the getCampaign URI to the retrieve the newly created campaign."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35006": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'fundingStrategy' is required for this call."
+ },
+ "35007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
+ },
+ "35019": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Campaign name is required for this call."
+ },
+ "35020": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
+ },
+ "35021": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A campaign with the name of {campaignName} already exists. Please provide a different name."
+ },
+ "35023": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
+ },
+ "35024": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign start date {startDate} cannot be after the end date {endDate}."
+ },
+ "35025": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A campaign start date is required."
+ },
+ "35026": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A campaign start or end date {date} cannot be in the past."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36101": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This functionality is not supported for the CPC funding model."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35062": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} has not ended yet. cloneCampaign is supported only for criterion based campaigns that have ended."
+ },
+ "35065": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This operation is only supported for criterion based campaigns."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35106": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'BidPercentage' should be provided when selected 'adRateStrategy' is 'FIXED'."
+ },
+ "35107": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'dynamicAdRatePreferences' can be provided only when selected 'adRateStrategy' is 'DYNAMIC'."
+ },
+ "35108": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adRateAdjustmentPercent' {adRateAdjustmentPercent} is not valid. Please set 'adRateAdjustmentPercent' {adRateAdjustmentPercent} between {minAllowedAdRateAdjustmentPercent}% - {maxAllowedAdRateAdjustmentPercent}%."
+ },
+ "35109": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adRateCapPercent' {adRateCapPercent} is not valid. Please set 'adRateCapPercent' between {minAllowedAdRateCapPercent}% - {maxAllowedAdRateCapPercent}%."
+ },
+ "35110": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adRateStrategy' is not supported for CPC funding model."
+ },
+ "35111": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'dynamicAdRatePreferences' is not supported for CPC funding model."
+ },
+ "35112": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adRateStrategy' is currently only supported for criterion based campaign with 'autoselectFutureInventory' as True."
+ },
+ "35113": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'dynamicAdRatePreferences' is currently only supported for criterion based campaign with 'autoselectFutureInventory' as True."
+ },
+ "35114": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'dynamicAdRatePreferences' list currently can only support one element containing dynamicAdRatePreference. Please remove additional elements and try again."
+ },
+ "35304": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "Another campaign cannot be created at this time, as the user is currently using a feature that only supports one campaign at a time."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error"
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "delete": {
- "tags": [
- "ad"
- ],
- "description": "This method removes the specified ad from the specified campaign.
Pass the ID of the ad to delete with the ID of the campaign associated with the ad as path parameters to the call.
Call getCampaigns to get the current list of the seller's campaign IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.
When using the CPC funding model, use the bulkUpdateAdsStatusByListingId method to change the status of ads to ARCHIVED.",
- "operationId": "deleteAd",
- "parameters": [
- {
- "name": "ad_id",
- "in": "path",
- "description": "Identifier of an ad. This ID was generated when the ad was created.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35044": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36101": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This functionality is not supported for the CPC funding model."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign": {
+ "get": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method retrieves the details for all of the seller's defined campaigns. Request parameters can be used to retrieve a specific campaign, such as the campaign's name, the start and end date, the channel, the status, and the funding model (i.e., Cost Per Sale (CPS) or Cost Per Click (CPC)). You can filter the result set by a campaign name, end date range, start date range, campaign channel, or campaign status. You can also paginate the records returned from the result set using the limit query parameter, and control which records to return using the offset parameter.
",
+ "operationId": "getCampaigns",
+ "parameters": [
+ {
+ "name": "campaign_name",
+ "in": "query",
+ "description": "This query parameter specifies the name of the campaign being retrieved. The results are filtered to include only the campaign by the specified name.
Use the getCampaigns method to retrieve a list of a seller's campaign names.
Note: The results might be null if other filters exclude the campaign with this name.
Maximum: 1 campaign name",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_status",
+ "in": "query",
+ "description": "This query parameter specifies the status of the campaign(s) being retrieved.
Note: The results might not include all the campaigns with this status if other filters exclude them.
Valid values: See CampaignStatusEnum
Maximum: 1 status",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_targeting_types",
+ "in": "query",
+ "description": "This query parameter specifies the targeting type of the campaign(s) to be retrieved.
The results will be filtered to only include campaigns with the specified targeting type. If not specified, all campaigns matching other filter parameters will be returned. The results might not include these campaigns if other search conditions exclude them.
Valid values: See CampaignTargetingTypeEnum",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "channels",
+ "in": "query",
+ "description": "This query parameter specifies the channel for the campaign(s) being retrieved.
The results will be filtered to only include campaigns with the specified channel. If not specified, all campaigns matching other filter parameters will be returned. The results might not include these campaigns if other search conditions exclude them.
Valid Values: See ChannelEnum",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "end_date_range",
+ "in": "query",
+ "description": "This query parameter specifies the range of a campaign's end date. The results are filtered to include only campaigns with an end date that is within specified range.
Valid format (UTC): yyyy-MM-ddThh:mm:ssZ..yyyy-MM-ddThh:mm:ssZ (campaign ends within this range)yyyy-MM-ddThh:mm:ssZ.. (campaign ends on or after this date)..yyyy-MM-ddThh:mm:ssZ (campaign ends on or before this date)2016-09-08T00:00.00.000Z..2016-09-09T00:00:00Z (campaign ends on September 08, 2016)
Note:The results might not include all the campaigns ending on this date if other filters exclude them.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "funding_strategy",
+ "in": "query",
+ "description": "This query parameter specifies the funding strategy for the campaign(s) being retrieved.
The results will be filtered to only include campaigns with the specified funding model. If not specified, all campaigns matching the other filter parameters will be returned. The results might not include these campaigns if other search conditions exclude them.
Valid Values: See FundingModelEnum",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "This query parameter specifies the maximum number of campaigns to return on a page in the paginated response.
Default: 10
Maximum: 500",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "This query parameter specifies the number of campaigns to skip in the result set before returning the first report in the paginated response.
Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "start_date_range",
+ "in": "query",
+ "description": "This query parameter specifies the range of a campaign's start date in which to filter the results. The results are filtered to include only campaigns with a start date that is equal to this date or is within specified range.
Valid format (UTC): yyyy-MM-ddThh:mm:ssZ..yyyy-MM-ddThh:mm:ssZ (starts within this range)yyyy-MM-ddThh:mm:ssZ (campaign starts on or after this date)..yyyy-MM-ddThh:mm:ssZ (campaign starts on or before this date)2016-09-08T00:00.00.000Z..2016-09-09T00:00:00Z (campaign starts on September 08, 2016)
Note: The results might not include all the campaigns with this start date if other filters exclude them.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CampaignPagedCollectionResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35020": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
+ },
+ "35023": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
+ },
+ "35027": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The date range {dateRange} is not valid. Ensure the beginning of the range is before the end of the range."
+ },
+ "35028": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The format of the date range {dateRange} is invalid. The format for a date range is yyyy-MM-ddThh:mm:ss.sssZ..yyyy-MM-ddThh:mm:ss.sssZ or yyyy-MM-ddThh:mm:ss.sssZ.. or ..yyyy-MM-ddThh:mm:ss.sssZ."
+ },
+ "35029": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
+ },
+ "35030": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'offset' cannot be less than zero."
+ },
+ "35043": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign status of {campaignStatus} is either invalid or not supported for this operation."
+ },
+ "35079": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Funding strategy needs to be one of {fundingStrategy} types."
+ },
+ "35123": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'campaignTargetingType' is not valid. Valid values for 'campaignTargetingType' are: {campaignTargetingTypeValues}."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "post": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method can be used to create a Promoted Listings general, priority, or offsite campaign.
A Promoted Listings campaign is the structure in which you place the ads or ad group for the listings you wish to promote.
Note: Campaigns can only contain ads for a maximum of 50,000 items.
General strategy campaigns utilize a Cost Per Sale (CPS) funding model. Sellers can set the ad rate and bidding strategies that are right for their business through the adRateStrategy, biddingStrategy, bidPercentage fields. For more information on general strategy campaigns, see Promoted Listings general strategy campaign flow.
Priority strategy campaigns utilize a Cost per Click (CPC) funding model. Sellers can create a daily budget through the budget container and choose what channel that their ads appear on. In addition, priority strategy campaigns give sellers the ability to create ad groups and specify keywords to ensure their ads reach their intended audience. For more information on priority strategy campaigns, see Promoted listings priority strategy campaign flow.
Promoted Offsite campaigns give sellers the ability to create their own advertising campaign and promote their eBay listing in leading external search channels. For more information on Promoted Offsite campaigns, see Promoted Offsite.
Note: Sellers can use the getAdvertisingEligibility method of the Account API v1 to determine their eligibility status for eBay advertising programs.
To create a basic campaign, supply: - The user-defined campaign name
- The start date (and optionally the end date) of the campaign
- The eBay marketplace on which the campaign is hosted
- Details on the campaign funding model
For details on creating Promoted Listings campaigns and how to select the items to be included in your campaigns, see Promoted Listings campaign creation.",
+ "operationId": "createCampaign",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the fields for the create campaign request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields for the create campaign request.",
+ "$ref": "#/components/schemas/CreateCampaignRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "201": {
+ "description": "Created",
+ "headers": {
+ "Location": {
+ "schema": {
+ "type": "string",
+ "description": "The location response header contains the getCampaign URI to the newly created campaign. The URL includes the eBay-assigned campaignId, which you can use to reference the campaign."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35103": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This campaign has reached maximum capacity of {maxSupportedNumber} listings. To continue promoting listings, create a new campaign."
+ },
+ "36410": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This campaign has been created with the suggested budget."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35003": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'campaignCriterion' is required for a criterion based campaign."
+ },
+ "35004": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "One of the selectionRule containers is empty. You must specify at least one rule in each selectionRule container. Note: 'categoryScope' is not a rule."
+ },
+ "35005": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'selectionRules' is required for criterion based campaigns."
+ },
+ "35006": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'fundingStrategy' is required for this call."
+ },
+ "35007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
+ },
+ "35008": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The category ID {categoryId} is not valid."
+ },
+ "35009": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing Condition ID {listingConditionId} is not valid. Refer to the API call documentation for a list of valid values."
+ },
+ "35015": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxPrice' or 'minPrice' value is missing or invalid. The value cannot be less than or equal to zero."
+ },
+ "35016": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'minPrice' {minPrice} cannot be greater than the 'maxPrice' {maxPrice}."
+ },
+ "35017": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'currency' is not valid or missing."
+ },
+ "35019": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Campaign name is required for this call."
+ },
+ "35020": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
+ },
+ "35021": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A campaign with the name of {campaignName} already exists. Please provide a different name."
+ },
+ "35022": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The brand name {brandName} is not valid."
+ },
+ "35023": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
+ },
+ "35024": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign start date {startDate} cannot be after the end date {endDate}."
+ },
+ "35025": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A campaign start date is required."
+ },
+ "35026": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A campaign start or end date {date} cannot be in the past."
+ },
+ "35038": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The funding model is required. Valid values for 'fundingModel' are: {fundingModelValues}."
+ },
+ "35039": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'categoryScope' is required for criterion based campaigns using category based listing selection rules. Valid values are: {categoryScopeValues}"
+ },
+ "35041": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'marketplaceId' is required."
+ },
+ "35042": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The criterion type is required for criterion based campaigns. Valid values are: {criterionTypeValues}."
+ },
+ "35124": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' {maxCpc} is not valid. Minimum value: {minMaxCpc} , Maximum value:{maxMaxCpc}."
+ },
+ "35125": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPreferences' list currently supports only one element. Please remove additional elements and try again."
+ },
+ "35134": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A 'biddingStrategy' cannot be supplied for smart targeting campaigns. Please either remove 'biddingStrategy' from the request to create a smart targeting campaign or supply another value for 'campaignTargetingType'."
+ },
+ "36101": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The daily budget value format is a maximum of two decimal points."
+ },
+ "36161": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Smart targeting campaigns require a `bidPreferences.maxCpc` value."
+ },
+ "36162": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' currency should be the same as the daily budget."
+ },
+ "36163": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' value {maxCpcValue} is below minimum value {maxCpcMinimumValue}."
+ },
+ "36164": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' value {maxCpcValue} is above maximum value {maxCpcMaximumValue}."
+ },
+ "36165": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' value {maxCpcValue} is more than maximum daily budget {maxDailyBudget}."
+ },
+ "36166": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' value {maxCpcValue} is invalid. Refer to the API call documentation for more information."
+ },
+ "36406": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'channels' value {channel} can only be used with the {funding_model} fundingModel."
+ },
+ "36407": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'channels' value is invalid."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35051": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}."
+ },
+ "35052": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
+ },
+ "35053": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "MarketplaceId: {marketplaceId} and Currency: {currency} for the listing selection rule do not match."
+ },
+ "35067": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The seller must accept the Promoted Listing terms and conditions. For the requirements to use the Promoted Listing API, refer to the documentation."
+ },
+ "35069": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "No more than {maxNumberOfSelectionRules} listing selection rules are allowed in a campaign."
+ },
+ "35072": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The number of listings that result from the rules exceeds the maximum number of listings allowed in a campaign, which is {maxSupportedNumber}. Refine the rules and submit the call again."
+ },
+ "35074": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "There were no eligible listings found for the selection rules provided. Please check the rules and submit the call again."
+ },
+ "35075": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35094": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "Maximum number of campaigns allowed with the 'channels' value {channel} is exceeded."
+ },
+ "35095": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'marketplaceId' {marketplaceId} is not supported. Offsite Ads is supported only on these marketplaces: {supportedMarketplaces}."
+ },
+ "35104": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'categoryScope' STORE can not be found. Please define the store categories first or use 'categoryScope' MARKETPLACE to select categories."
+ },
+ "35106": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'BidPercentage' should be provided when selected 'adRateStrategy' is 'FIXED'."
+ },
+ "35107": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'dynamicAdRatePreferences' can be provided only when selected 'adRateStrategy' is 'DYNAMIC'."
+ },
+ "35108": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adRateAdjustmentPercent' {adRateAdjustmentPercent} is not valid. Please set 'adRateAdjustmentPercent' {adRateAdjustmentPercent} between {minAllowedAdRateAdjustmentPercent}% - {maxAllowedAdRateAdjustmentPercent}%."
+ },
+ "35109": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adRateCapPercent' {adRateCapPercent} is not valid. Please set 'adRateCapPercent' between {minAllowedAdRateCapPercent}% - {maxAllowedAdRateCapPercent}%."
+ },
+ "35110": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adRateStrategy' is not supported for CPC funding model."
+ },
+ "35111": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'dynamicAdRatePreferences' is not supported for CPC funding model."
+ },
+ "35114": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'dynamicAdRatePreferences' list currently can only support one element containing dynamicAdRatePreference. Please remove additional elements and try again."
+ },
+ "35127": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'maxCPC' is only supported for CPC funding model campaigns with on-site channels and smart targeting type."
+ },
+ "35128": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'campaignTargetingType' is only supported for CPC funding model campaigns with on-site channels."
+ },
+ "35132": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'biddingStrategy' field is not supported for CPS funding model."
+ },
+ "35304": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "Another campaign cannot be created at this time, as the user is currently using a feature that only supports one campaign at a time."
+ },
+ "36151": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'campaignCriterion' {campaignCriterion} is not supported for CPC funding model."
+ },
+ "36152": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'bidPercentage' is not supported for CPC funding model."
+ },
+ "36153": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The daily budget currency {currency} is not supported for {fieldName}. The supported currency for the {marketplaceId} marketplace is {supportedCurrencyCode}."
+ },
+ "36154": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The daily budget below minimum allowed {minAllowed}."
+ },
+ "36155": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The daily budget above maximum allowed {maxAllowed}."
+ },
+ "36156": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "campaignBudget is not supported for CPS funding model."
+ },
+ "36157": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The daily budget is required for campaigns with CPC funding model."
+ },
+ "36158": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The daily budget value format {dailyBudgetValue} cannot have more than 2 decimal places."
+ },
+ "36159": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'marketplaceId' {marketPlaceId} is not supported. Promoted Listings with CPC funding model is supported only on these marketplaces: {supportedMarketplaces}."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/delete_ads_by_inventory_reference": {
- "post": {
- "tags": [
- "ad"
- ],
- "description": "This method works with listings that are managed with the Inventory API. The method deletes ads using a list of seller-defined inventory reference IDs, used with the Inventory API, that are associated with the specified campaign ID.
Specify the campaign ID (as a path parameter) and a list of inventoryReferenceId and inventoryReferenceType pairs to be deleted.
Call getCampaigns to get a list of the seller's current campaign IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.
When using the CPC funding model, use the bulkUpdateAdsStatusByInventoryReference method to change the status of ads to ARCHIVED.",
- "operationId": "deleteAdsByInventoryReference",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This request object defines the fields for the deleteAdsByInventoryReference request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This request object defines the fields for the deleteAdsByInventoryReference request.",
- "$ref": "#/components/schemas/DeleteAdsByInventoryReferenceRequest"
- }
+ "/ad_campaign/{campaign_id}": {
+ "get": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method retrieves the details of a single campaign, as specified with the campaign_id query parameter. This method returns all the details of a campaign (including the campaign's the selection rules), except the for the listing IDs or inventory reference IDs included in the campaign. These IDs are returned by getAds.
Call getCampaigns to retrieve a list of the seller's campaign IDs.
",
+ "operationId": "getCampaign",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign being retrieved.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Campaign"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Business error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developers support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "delete": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method deletes the campaign specified by the campaign_id query parameter.
Note: You can only delete campaigns that have ended.
Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.",
+ "operationId": "deleteCampaign",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign being deleted.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35056": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The state of the campaign cannot be changed as requested."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "required": true
},
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/AdIds"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35012": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference ID {inventoryReferenceId} is not valid."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35040": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36101": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This functionality is not supported for the CPC funding model."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35072": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the inventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP'"
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign/{campaign_id}/end": {
+ "post": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method ends an active (RUNNING) or paused campaign. Specify the campaign you want to end by supplying its campaign ID in a query parameter. Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.
",
+ "operationId": "endCampaign",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the RUNNING or PAUSED ad campaign that is being ended.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35056": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The state of the campaign cannot be changed as requested."
+ },
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/get_ads_by_inventory_reference": {
- "get": {
- "tags": [
- "ad"
- ],
- "description": "This method retrieves Promoted Listings ads associated with listings that are managed with the Inventory API from the specified campaign.
Supply the campaign_id as a path parameter and use query parameters to specify the inventory_reference_id and inventory_reference_type pairs.
In the Inventory API, an inventory reference ID is either a seller-defined SKU value or an inventoryItemGroupKey (a seller-defined ID for an inventory item group, which is an entity that's used in the Inventory API to create a multiple-variation listing). To indicate a listing managed by the Inventory API, you must always specify both an inventory_reference_id and the associated inventory_reference_type.
Call getCampaigns to retrieve all of the seller's the current campaign IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
- "operationId": "getAdsByInventoryReference",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "inventory_reference_id",
- "in": "query",
- "description": "The inventory reference ID associated with the ad you want returned. A seller's inventory reference ID is the ID of either a listing or the ID of an inventory item group (the parent of a multi-variation listing, such as a shirt that is available in multiple sizes and colors). You must always supply in both an inventory_reference_id and an inventory_reference_type.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "inventory_reference_type",
- "in": "query",
- "description": "The type of the inventory reference ID. Set this value to either INVENTORY_ITEM (a single listing) or INVENTORY_ITEM_GROUP (a multi-variation listing). You must always pass in both an inventory_reference_id and an inventory_reference_type. ",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Ads"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35012": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference ID {inventoryReferenceId} is not valid."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35040": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36106": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'adGroupId' is not supported for CPS funding model."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign/find_campaign_by_ad_reference": {
+ "get": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method retrieves the campaigns containing the listing that is specified using either a listing ID, or an inventory reference ID and inventory reference type pair. The request accepts either a listing_id, or an inventory_reference_id and inventory_reference_type pair, as used in the Inventory API.
eBay listing IDs are generated by either the Trading API or the Inventory API when you create a listing.
An inventory reference ID can be either a seller-defined SKU or inventoryItemGroupKey, as specified in the Inventory API.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
+ "operationId": "findCampaignByAdReference",
+ "parameters": [
+ {
+ "name": "inventory_reference_id",
+ "in": "query",
+ "description": "This query parameter specifies the unique identifier of a single-item listing or a multi-variation listing associated with the campaign being retrieved.
To retrieve an campaign for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).
To retrieve an campaign for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API.
Note: You must always pass in both inventory_reference_id and inventory_reference_type.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "inventory_reference_type",
+ "in": "query",
+ "description": "This query parameter specifies the type of the seller's inventory reference ID, which is a listing or group of items.
See InventoryReferenceTypeEnum for supported values.
Note: You must always pass in both inventory_reference_id and inventory_reference_type.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "listing_id",
+ "in": "query",
+ "description": "This query parameter specifies the unique identifier of the eBay listing associated with the ad being used to retrieve the campaign.
eBay listing IDs are generated by either the Trading API or the Inventory API when you create a listing.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Campaigns"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35013": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID {listingId} is not valid."
+ },
+ "35014": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID is required for this call."
+ },
+ "35031": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A 'listing_id' or an 'inventory_reference_id' and 'inventory_reference_type' is required for this call."
+ },
+ "35032": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A 'listing_id' and an 'inventory_reference_id' cannot be used together in the same call. To use both in a campaign, you must submit two calls."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Business error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/ad/{ad_id}/update_bid": {
- "post": {
- "tags": [
- "ad"
- ],
- "description": "This method updates the bid percentage (also known as the \"ad rate\") for the specified ad in the specified campaign. In the request, supply the campaign_id and ad_id as path parameters, and supply the new bidPercentage value in the payload of the call.
Call getCampaigns to retrieve a seller's current campaign IDs and call getAds to get their ad IDs.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
- "operationId": "updateBid",
- "parameters": [
- {
- "name": "ad_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad that's generated when an ad is created.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This type defines the fields for the updateBid request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the fields for the updateBid request.",
- "$ref": "#/components/schemas/UpdateBidPercentageRequest"
- }
+ "/ad_campaign/get_campaign_by_name": {
+ "get": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method retrieves the details of a single campaign, as specified with the campaign_name query parameter. Note that the campaign name you specify must be an exact, case-sensitive match of the name of the campaign you want to retrieve.Call getCampaigns to retrieve a list of the seller's campaign names.
",
+ "operationId": "getCampaignByName",
+ "parameters": [
+ {
+ "name": "campaign_name",
+ "in": "query",
+ "description": "This query parameter specifies name of the campaign being retrieved.
Use the getCampaigns method to retrieve a list of a seller's campaign names.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Campaign"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35019": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Campaign name is required for this call."
+ },
+ "35020": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
+ },
+ "35023": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
+ },
+ "35046": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found with the name {campaign_name}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Business error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "required": true
},
- "responses": {
- "204": {
- "description": "No content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35044": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "35048": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID {listingId} is invalid or has ended."
- },
- "36101": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This functionality is not supported for the CPC funding model."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35052": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
- },
- "35058": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} is not a fixed price item. This is a requirement for a promoted listing."
- },
- "35059": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing ID {listingId} is not a multi-quantity item. This is a requirement for a promoted listing."
- },
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35064": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for key based campaigns."
- },
- "35075": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "35113": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is not supported when selected adRateStratergy is DYNAMIC for the campaign."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign/{campaign_id}/pause": {
+ "post": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method pauses an active (RUNNING) campaign. You can restart the campaign by calling resumeCampaign, as long as the campaign's end date is in the future.
Note:The listings associated with a paused campaign cannot be added into another campaign.
Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.",
+ "operationId": "pauseCampaign",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the RUNNING ad campaign being paused.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35056": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The state of the campaign cannot be changed as requested."
+ },
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35303": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The status of this campaign cannot be modified through this API. Refer to the API call documentation for more information."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/ad_group": {
- "get": {
- "tags": [
- "ad_group"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method retrieves ad groups for the specified campaigns.
Each campaign can only have one ad group.
In the request, supply the campaign_ids as path parameters.
Call getCampaigns to retrieve a list of the current campaign IDs for a seller.",
- "operationId": "getAdGroups",
- "parameters": [
- {
- "name": "ad_group_status",
- "in": "query",
- "description": "A comma-separated list of ad group statuses. The results will be filtered to only include the given statuses of the ad group.
The results might not include these ad groups if other search conditions exclude them.",
- "required": false,
- "schema": {
- "type": "string"
+ "/ad_campaign/{campaign_id}/resume": {
+ "post": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method resumes a paused campaign, as long as its end date is in the future. Supply the campaign_id for the campaign you want to restart as a query parameter in the request.
Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.
",
+ "operationId": "resumeCampaign",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the paused ad campaign that is being resumed.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35056": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The state of the campaign cannot be changed as requested."
+ },
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
+ },
+ "/ad_campaign/suggest_budget": {
+ "get": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "Note: This method is only supported for Promoted Offsite campaigns. Sellers can use the getAdvertisingEligibility method of the Account API v1 to determine if they are eligible for offsite campaigns.
This method allows sellers to retrieve the suggested budget for an offsite campaign.",
+ "operationId": "suggestBudget",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.
See MarketplaceIdEnum for supported values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SuggestBudgetResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35041": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'marketplaceId' is required."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35095": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'marketplaceId' {marketplaceId} is not supported. Offsite Ads is supported only on these marketplaces: {supportedMarketplaces}."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "limit",
- "in": "query",
- "description": "The number of results, from the current result set, to be returned in a single page.",
- "required": false,
- "schema": {
- "type": "string"
+ },
+ "/ad_campaign/{campaign_id}/suggest_items": {
+ "get": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method allows sellers to obtain ideas for listings, which can be targeted for Promoted Listings campaigns.",
+ "operationId": "suggestItems",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which suggestions are being provided.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "category_ids",
+ "in": "query",
+ "description": "Specifies the category ID that is used to limit the results. This refers to an exact leaf category (the lowest level in that category and has no children). This field can have one category ID, or a comma-separated list of IDs. To return all category IDs, set to null.
Use the getCategorySuggestions method to retrieve category IDs.
Maximum: 10 ",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "Specifies the maximum number of campaigns to return on a page in the paginated response. If no value is specified, the default value is used.
Default: 10
Minimum: 1
Maximum: 1000",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "Specifies the number of campaigns to skip in the result set before returning the first report in the paginated response.
Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/TargetedAdsPagedCollection"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35008": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The category Id {categoryId} is not valid."
+ },
+ "35029": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
+ },
+ "35030": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'offset' cannot be less than zero."
+ },
+ "35041": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'marketplaceId' is required."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "35090": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Category ID limit exceeded. You can pass up to a maximum of {maxCategoryLimit} category IDs per request."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35051": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "offset",
- "in": "query",
- "description": "The number of results that will be skipped in the result set. This is used with the limit field to control the pagination of the output.
For example, if the offset is set to 0 and the limit is set to 10, the method will retrieve items 1 through 10 from the list of items returned. If the offset is set to 10 and the limit is set to 10, the method will retrieve items 11 through 20 from the list of items returned.
Default: 0",
- "required": false,
- "schema": {
- "type": "string"
+ },
+ "/ad_campaign/suggest_max_cpc": {
+ "post": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "Note: This method is only supported for smart targeting priority strategy campaigns. Sellers can use the getAdvertisingEligibility method of the Account API v1 to determine if they are eligible for a priority strategy campaign.
This method allows sellers to retrieve the suggested maximum cost-per-click value for a smart targeting campaign. This value is required when creating a smart targeting campaign and indicates the maximum amount for which the eBay suggested bid can be adjusted.",
+ "operationId": "suggestMaxCpc",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the fields used in the suggestMaxCpc request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields used in the suggestMaxCpc request.",
+ "$ref": "#/components/schemas/SuggestMaxCpcRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields used in the suggestMaxCpc response.",
+ "$ref": "#/components/schemas/SuggestMaxCpcResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35041": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'marketplaceId' is required."
+ },
+ "35135": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Please supply one or more values in the ālistingIdsā field in the request."
+ },
+ "35136": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The following values you supplied in the ālistingIdsā field are invalid: {listingIds}"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35051": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}."
+ },
+ "35057": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The listing Id {listingId} does not belong to the seller making this call"
+ },
+ "35068": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing Ids. Only {maxSupportedNumber} listings are supported per call."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/AdGroupPagedCollectionResponse"
- }
- }
+ },
+ "/ad_campaign/{campaign_id}/update_ad_rate_strategy": {
+ "post": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method updates the ad rate strategy for an existing rules-based general strategy ad campaign that uses the Cost Per Sale (CPS) funding model.
Specify the campaign_id as a path parameter. You can retrieve the campaign IDs for a seller by calling the getCampaigns method.
Note: This method only applies to the CPS funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
+ "operationId": "updateAdRateStrategy",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which the ad rate strategy is being updated.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the request fields for the ad rate strategy that shall be updated.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the request fields for the ad rate strategy that shall be updated.",
+ "$ref": "#/components/schemas/UpdateAdrateStrategyRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "No content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35007": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35043": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign status of {campaignStatus} is either invalid or not supported for this operation."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35106": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'BidPercentage' should be provided when selected 'adRateStrategy' is 'FIXED'."
+ },
+ "35107": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'dynamicAdRatePreferences' can be provided only when selected 'adRateStrategy' is 'DYNAMIC'."
+ },
+ "35108": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adRateAdjustmentPercent' {adRateAdjustmentPercent} is not valid. Please set 'adRateAdjustmentPercent' {adRateAdjustmentPercent} between {minAllowedAdRateAdjustmentPercent}% - {maxAllowedAdRateAdjustmentPercent}%."
+ },
+ "35109": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adRateCapPercent' {adRateCapPercent} is not valid. Please set 'adRateCapPercent' between {minAllowedAdRateCapPercent}% - {maxAllowedAdRateCapPercent}%."
+ },
+ "35110": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adRateStrategy' is not supported for CPC funding model."
+ },
+ "35111": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'dynamicAdRatePreferences' is not supported for CPC funding model."
+ },
+ "35114": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'dynamicAdRatePreferences' list currently can only support one element containing dynamicAdRatePreference. Please remove additional elements and try again."
+ },
+ "35308": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'adRateStrategy' of this campaign cannot be modified through this API. Refer to the API call documentation for more information."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35029": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
- },
- "35030": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'offset' cannot be less than zero."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- }
- }
+ },
+ "/ad_campaign/{campaign_id}/update_bidding_strategy": {
+ "post": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method allows sellers to change the bidding strategy for a specified Cost Per Click (CPC) campaign that uses manual targeting. Available bidding strategies are:FIXED
When using a fixed bidding strategy, sellers manually assign and adjust keyword bids for the CPC campaign.DYNAMIC
When using a dynamic bidding strategy, eBay will manage a campaign's keyword bids and automatically update them daily to the suggested bid.
Note: For a CPC campaign using dynamic bidding, sellers can continue to manually add keywords for the campaign, but they are no longer able to manually adjust their associated bid values. In order to manually adjust bid values, sellers must use the FIXED bidding strategy.
In addition, this method allows sellers to modify the maxCPC value of a smart targeting campaign.
Note: This method only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model. Refer to Funding Models in the Promoted Listings Playbook for more information.",
+ "operationId": "updateBiddingStrategy",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which the keyword bidding strategy is being updated.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type specifies the new value for the bidding strategy.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type specifies the new value for the bidding strategy.",
+ "$ref": "#/components/schemas/UpdateBiddingStrategyRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "No content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "35124": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' {maxCpc} is not valid. Minimum value: {minMaxCpc} , Maximum value:{maxMaxCpc}."
+ },
+ "35125": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bidPreferences' list currently supports only one element. Please remove additional elements and try again."
+ },
+ "35130": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'biddingStrategy' is required"
+ },
+ "36101": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This functionality is not supported for CPS funding model."
+ },
+ "36161": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Smart targeting campaigns require a `bidPreferences.maxCpc` value."
+ },
+ "36162": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' currency should be the same as the daily budget."
+ },
+ "36163": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' value {maxCpcValue} is below minimum value {maxCpcMinimumValue}."
+ },
+ "36164": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' value {maxCpcValue} is above maximum value {maxCpcMaximumValue}."
+ },
+ "36165": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' value {maxCpcValue} is more than maximum daily budget {maxDailyBudget}."
+ },
+ "36166": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCpc' value {maxCpcValue} is invalid. Refer to the API call documentation for more information."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35126": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'biddingStrategy' isn't applicable for campaigns with smart targeting type. "
+ },
+ "35127": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "'maxCPC' is only supported for CPC funding model campaigns with on-site channels and smart targeting type."
+ },
+ "35134": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "A 'biddingStrategy' cannot be supplied for smart targeting campaigns. Please either remove 'biddingStrategy' from the request to create a smart targeting campaign or supply another value for 'campaignTargetingType'."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error"
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ },
+ "/ad_campaign/{campaign_id}/update_campaign_budget": {
+ "post": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method updates the daily budget for a priority strategy campaign that uses the Cost Per Click (CPC) funding model.
A click occurs when an eBay user finds and clicks on the sellerās listing (within the search results) after using a keyword that the seller has created for the campaign. For each ad in an ad group in the campaign, each click triggers a cost, which gets subtracted from the campaignās daily budget. If the cost of the clicks exceeds the daily budget, the Promoted Listings campaign will be paused until the next day.
Specify the campaign_id as a path parameter. You can retrieve the campaign IDs for a seller by calling the getCampaigns method.
Note: The daily budget for a campaign can only be updated 15 times per day. If this limit is exceeded, an error will occur and you will be blocked from updating the budget until the next day.",
+ "operationId": "updateCampaignBudget",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which the budget is being updated.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the request fields for the budget details that shall be updated.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the request fields for the budget details that shall be updated.",
+ "$ref": "#/components/schemas/UpdateCampaignBudgetRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "36169": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You can update your budget one more time today."
+ },
+ "36170": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "Youāve reached the daily update limit for daily budget changes."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36100": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This functionality is not supported for CPS funding model."
+ },
+ "36101": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The daily budget value format is a maximum of two decimal points."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "36153": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The daily budget currency {currency} is not supported for {fieldName}. The supported currency for the {marketplaceId} marketplace is {supportedCurrencyCode}."
+ },
+ "36154": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The daily budget below minimum allowed {minAllowed}."
+ },
+ "36155": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The daily budget above maximum allowed {maxAllowed}."
+ },
+ "36156": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "campaignBudget is not supported for CPS funding model."
+ },
+ "36157": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The daily budget is required for campaigns with CPC funding model."
+ },
+ "36158": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The daily budget value format {dailyBudgetValue} cannot have more than 2 decimal places."
+ },
+ "36167": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The daily budget change must be at least 0.50 {currencyCode}."
+ },
+ "36168": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the allowed limit on daily budget changes for this campaign."
+ },
+ "36408": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The seller must accept the new pricing policy before the campaign can be updated."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "post": {
- "tags": [
- "ad_group"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method adds an ad group to an existing PLA campaign that uses the Cost Per Click (CPC) funding model.
To create an ad group for a campaign, specify the defaultBid for the ad group in the payload of the request. Then specify the campaign to which the ad group should be associated using the campaign_id path parameter.
Each campaign can have one or more associated ad groups.",
- "operationId": "createAdGroup",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
+ "/ad_campaign/{campaign_id}/update_campaign_identification": {
+ "post": {
+ "tags": [
+ "campaign"
+ ],
+ "description": "This method can be used to change the name of a campaign, as well as modify the start or end dates. Specify the campaign_id you want to update as a URI parameter, and configure the campaignName and startDate in the request payload.
If you want to change only the end date of the campaign, specify the current campaign name, set endDate as desired, and set startDate to the actual start date of the campaign. This applies if the campaign status is RUNNING or PAUSED. You can retrieve the startDate using the getCampaign method.
Note that if you do not set a new end date in this call, any current endDate value will be set to null. To preserve the currently-set end date, you must specify the value again in your request.
Call getCampaigns to retrieve a seller's campaign details, including the campaign ID, campaign name, and the start and end dates of the campaign.",
+ "operationId": "updateCampaignIdentification",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign being updated.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the fields to update the campaign name and start and end dates.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields to update the campaign name and start and end dates.",
+ "$ref": "#/components/schemas/UpdateCampaignIdentificationRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "No content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35019": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Campaign name is required for this call."
+ },
+ "35020": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
+ },
+ "35021": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A campaign with the name of {campaignName} already exists. Please provide a different name."
+ },
+ "35023": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
+ },
+ "35024": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign start date {startDate} cannot be after the end date {endDate}."
+ },
+ "35025": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A campaign start date is required."
+ },
+ "35026": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A campaign start or end date {date} cannot be in the past."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35055": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The start date cannot be modified for an active campaign."
+ },
+ "35061": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
+ },
+ "35063": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
+ },
+ "35077": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
+ },
+ "35078": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
+ },
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35306": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'endDate' of this campaign cannot be modified through this API. Refer to the API call documentation for more information."
+ },
+ "35307": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'campaignName' of this campaign cannot be modified through this API. Refer to the API call documentation for more information."
+ },
+ "36408": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The seller must accept the new pricing policy before the campaign can be updated."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
+ },
+ "/ad_campaign/{campaign_id}/bulk_create_keyword": {
+ "post": {
+ "tags": [
+ "keyword"
+ ],
+ "description": "This method adds keywords, in bulk, to an existing priority strategy ad group in a campaign that uses manual targeting.
This method also sets the CPC rate for each keyword, depending on the selected bidding strategy, as follows:
FIXED: If the seller provides a keyword bid, that bid value will be used.
If no bid is provided, the adgroup's default bid value will be used.DYNAMIC: The eBay suggested bid will be used.
If the seller passes in a value, a warning will be returned.
In the request, supply the campaign_id as a path parameter.
Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller.",
+ "operationId": "bulkCreateKeyword",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which a set of keywords is being created.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "A type that defines the fields for the bulk request to create keywords.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "A type that defines the fields for the bulk request to create keywords.",
+ "$ref": "#/components/schemas/BulkCreateKeywordRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkCreateKeywordResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35133": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The bid provided in the call was ignored because the selected biddingStrategy is DYNAMIC for the campaign."
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35033": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one request is required for bulk requests."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ad group found for ad group id {ad_group_id}."
+ },
+ "36219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The ad group with ad group id {ad_group_id} has been archived."
+ },
+ "36301": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keyword match type {matchType} is not supported. Valid values are: {matchTypeValues}."
+ },
+ "36303": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A keyword with text {keywordText} and match type {matchType} already exists for this Ad Group."
+ },
+ "36304": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keywordText {keywordText} cannot be more than {maxKeywordTextLength} characters."
+ },
+ "36305": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is not valid. The default bid value should be a double precision value."
+ },
+ "36306": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is below floor value {bidFloorValue}."
+ },
+ "36307": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is above max value {bidMaxValue}."
+ },
+ "36308": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' currency {bidCurrency} is not valid or missing."
+ },
+ "36309": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' currency {bidCurrency} should be the same as the daily budget."
+ },
+ "36311": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keywordText cannot be null or empty."
+ },
+ "36312": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keywordText contains invalid characters {invalidCharacters}"
+ },
+ "36313": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is more than maximum daily budget {maxDailyBudget}."
+ },
+ "36315": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "There are duplicate KeywordText and matchType combination in this request. You must remove the duplicate."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ },
+ "36316": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of Keyword requests in a bulk request. Only {maxSupportedRequestNumberInBulk} Ids are supported per call."
+ },
+ "36319": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of create Keyword for an Ad Group. Only {maxSupportedNumber} Ids are supported per Ad Group."
+ },
+ "36320": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The keywordText {keywordText} cannot have total number of words more than {maxWordsInKeyword} words."
+ },
+ "36322": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "Total keyword requests exceed the current AdGroup keyword capacity, which is {maxSupportedRequestNumber}."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
- ],
- "requestBody": {
- "description": "This type defines the fields for the createAdGroup request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the fields for the createAdGroup request.",
- "$ref": "#/components/schemas/CreateAdGroupRequest"
- }
+ },
+ "/ad_campaign/{campaign_id}/bulk_update_keyword": {
+ "post": {
+ "tags": [
+ "keyword"
+ ],
+ "description": "This method updates the bids and statuses of keywords, in bulk, for an existing priority strategy campaign.
In the request, supply the campaign_id as a path parameter.
Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller.",
+ "operationId": "bulkUpdateKeyword",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which a set of keywords is being updated.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "A type that defines the fields for the bulk request to update keywords.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "A type that defines the fields for the bulk request to update keywords.",
+ "$ref": "#/components/schemas/BulkUpdateKeywordRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkUpdateKeywordResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35133": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The bid provided in the call was ignored because the selected biddingStrategy is DYNAMIC for the campaign."
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36305": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is not valid. The default bid value should be a double precision value."
+ },
+ "36306": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is below floor value {bidFloorValue}."
+ },
+ "36307": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is above max value {bidMaxValue}."
+ },
+ "36308": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' currency {bidCurrency} is not valid or missing."
+ },
+ "36309": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' currency {bidCurrency} should be the same as the daily budget."
+ },
+ "36310": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No keyword found for keyword id {keyword_id}."
+ },
+ "36313": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is more than maximum daily budget {maxDailyBudget}."
+ },
+ "36317": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' or 'keywordStatus' is missing, either one is required for update."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ },
+ "36316": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of Keyword requests in a bulk. Only {maxSupportedNumberInBulk} Ids are supported per call."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "required": true
},
- "responses": {
- "201": {
- "description": "Created",
- "headers": {
- "Location": {
- "schema": {
- "type": "string",
- "description": "The location response header contains the getAdGroup URL to the newly created ad group. The URL includes the newly assigned adGroupID, which you can use to retrieve the ad group."
- }
- }
+ "/ad_campaign/{campaign_id}/keyword": {
+ "get": {
+ "tags": [
+ "keyword"
+ ],
+ "description": "This method can be used to retrieve all of the keywords for ad groups in priority strategy campaigns that use the Cost Per Click (CPC) funding model.
In the request, specify the campaign_id as a path parameter. If one or more ad_group_ids are passed in the request body, the keywords for those ad groups will be returned. If ad_group_ids are not passed in the response body, the call will return all the keywords in the campaign.
Call the getCampaigns method to retrieve a list of current campaign IDs for a seller.",
+ "operationId": "getKeywords",
+ "parameters": [
+ {
+ "name": "ad_group_ids",
+ "in": "query",
+ "description": "A comma-separated list of ad group IDs. This query parameter is used if the seller wants to retrieve keywords from one or more specific ad groups. If this query parameter is not used, all keywords that are part of the CPC campaign are returned.
Use the getAdGroups method to retrieve the ad group IDs for a seller.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the keyword(s) being retrieved.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "keyword_status",
+ "in": "query",
+ "description": "A comma-separated list of keyword statuses. The results will be filtered to only include the given statuses of the keyword. If none are provided, all keywords are returned.
See KeywordStatusEnum for supported values.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "Specifies the maximum number of results to return on a page in the paginated response.
Default: 10
Maximum: 500",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "Specifies the number of results to skip in the result set before returning the first report in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/KeywordPagedCollectionResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35029": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
+ },
+ "35030": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'offset' cannot be less than zero."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36314": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Ad Group Ids should be delimited by {adGroupIdsDelimiter}"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
},
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36201": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "An ad group with name {name} already exists for this campaign."
- },
- "36202": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The ad group name cannot be more than {maxAdGroupNameLength} characters."
- },
- "36203": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' value {defaultBidValue} is not valid. The default bid value should be a double precision value."
- },
- "36204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' currency {defaultBidCurrency} is not valid or missing."
- },
- "36205": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' value {defaultBidValue} is below floor value {bidFloorValue}."
- },
- "36206": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' value {defaultBidValue} is above max value {bidMaxValue}."
- },
- "36207": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' value {defaultBidValue} is more than daily budget."
- },
- "36212": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' currency {defaultBidCurrency} should be the same as the daily budget."
- },
- "36214": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Ad Group name is required for this call."
- },
- "36215": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' is required for this call."
- },
- "36216": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' value is required for this call."
- },
- "36217": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The Ad Group name contains invalid characters. {notAllowedCharacters} are not allowed."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "36213": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign funding model should be CPC. Please check funding model for provided campaign id."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "post": {
+ "tags": [
+ "keyword"
+ ],
+ "description": "This method creates keywords using a specified campaign ID for an existing priority strategy campaign that uses manual targeting.
In the request, supply the campaign_id as a path parameter.
Call the suggestKeywords method to retrieve a list of keyword ideas to be targeted for priority strategy campaigns, and call the getCampaigns method to retrieve a list of current campaign IDs for a seller.",
+ "operationId": "createKeyword",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which a keyword is being created.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "A type that defines the fields for the request to create a keyword.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "A type that defines the fields for the request to create a keyword.",
+ "$ref": "#/components/schemas/CreateKeywordRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "201": {
+ "description": "Created",
+ "headers": {
+ "Location": {
+ "schema": {
+ "type": "string",
+ "description": "The location response header contains the getKeyword URI of the newly created keyword. The URI includes the newly created keywordId, which you can use to reference the keyword."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35133": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The bid provided in the call was ignored because the selected biddingStrategy is DYNAMIC for the campaign."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ad group found for ad group id {ad_group_id}."
+ },
+ "36219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The ad group with ad group id {ad_group_id} has been archived."
+ },
+ "36301": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keyword match type {matchType} is not supported. Valid values are: {matchTypeValues}."
+ },
+ "36303": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A keyword with text {keywordText} and match type {matchType} already exists for this Ad Group."
+ },
+ "36304": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keywordText {keywordText} cannot be more than {maxKeywordTextLength} characters."
+ },
+ "36305": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is not valid. The default bid value should be a double precision value."
+ },
+ "36306": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is below floor value {bidFloorValue}."
+ },
+ "36307": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is above max value {bidMaxValue}."
+ },
+ "36308": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' currency {bidCurrency} is not valid or missing."
+ },
+ "36309": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' currency {bidCurrency} should be the same as the daily budget."
+ },
+ "36311": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keywordText cannot be null or empty."
+ },
+ "36312": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keywordText contains invalid characters {invalidCharacters}"
+ },
+ "36313": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is more than maximum daily budget {maxDailyBudget}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ },
+ "36319": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of create Keyword for an Ad Group. Only {maxSupportedNumber} Ids are supported per Ad Group."
+ },
+ "36320": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The keywordText {keywordText} cannot have total number of words more than {maxWordsInKeyword} words."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/ad_group/{ad_group_id}": {
- "get": {
- "tags": [
- "ad_group"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method retrieves the details of a specified ad group, such as the ad groupās default bid and status.
In the request, specify the campaign_id and ad_group_id as path parameters.
Call getCampaigns to retrieve a list of the current campaign IDs for a seller and call getAdGroups for the ad group ID of the ad group you wish to retrieve.",
- "operationId": "getAdGroup",
- "parameters": [
- {
- "name": "ad_group_id",
- "in": "path",
- "description": "The ID of the ad group that shall be retrieved.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/AdGroup"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No ad group found for ad group id {ad_group_id}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "36213": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign funding model should be CPC. Please check funding model for provided campaign id."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/ad_campaign/{campaign_id}/keyword/{keyword_id}": {
+ "get": {
+ "tags": [
+ "keyword"
+ ],
+ "description": "This method retrieves details on a specific keyword from an ad group within a priority strategy campaign that uses the Cost Per Click (CPC) funding model.
In the request, specify the campaign_id and keyword_id as path parameters.
Call the getCampaigns method to retrieve a list of current campaign IDs for a seller and call the getKeywords method to retrieve their keyword IDs.",
+ "operationId": "getKeyword",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the keyword being retrieved.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "keyword_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the keyword being retrieved.
Use the getKeywords method to retrieve keyword IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Keyword"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36310": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No keyword found for keyword id {keyword_id}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "put": {
+ "tags": [
+ "keyword"
+ ],
+ "description": "This method updates keywords using a campaign ID and keyword ID for an existing priority strategy campaign.
In the request, specify the campaign_id and keyword_id as path parameters.
Call the getCampaigns method to retrieve a list of current campaign IDs for a seller and call the getKeywords method to retrieve their keyword IDs.",
+ "operationId": "updateKeyword",
+ "parameters": [
+ {
+ "name": "campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the keyword being updated.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "keyword_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier of the keyword being updated.
Use the getKeywords method to retrieve keyword IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "A type that defines the fields for the request to update a keyword.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "A type that defines the fields for the request to update a keyword.",
+ "$ref": "#/components/schemas/UpdateKeywordRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UpdateKeywordResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35133": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The bid provided in the call was ignored because the selected biddingStrategy is DYNAMIC for the campaign."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36305": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is not valid. The default bid value should be a double precision value."
+ },
+ "36306": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is below floor value {bidFloorValue}."
+ },
+ "36307": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is above max value {bidMaxValue}."
+ },
+ "36308": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' currency {bidCurrency} is not valid or missing."
+ },
+ "36309": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' currency {bidCurrency} should be the same as the daily budget."
+ },
+ "36310": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No keyword found for keyword id {keyword_id}."
+ },
+ "36313": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' value {bidValue} is more than maximum daily budget {maxDailyBudget}."
+ },
+ "36317": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'bid' or 'keywordStatus' is missing, either one is required for update."
+ },
+ "36318": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The keyword with 'keyword_id' {keyword_Id} is already archived and cannot be updated."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ },
+ "35002": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal error. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "put": {
- "tags": [
- "ad_group"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method updates the ad group associated with a campaign.
With this method, you can modify the default bid for the ad group, change the state of the ad group, or change the name of the ad group. Pass the ad_group_id you want to update as a URI parameter, and configure the adGroupStatus and defaultBid in the request payload.
Call getAdGroup to retrieve the current default bid and status of the ad group that you would like to update.",
- "operationId": "updateAdGroup",
- "parameters": [
- {
- "name": "ad_group_id",
- "in": "path",
- "description": "The ID of the ad group that shall be updated.",
- "required": true,
- "schema": {
- "type": "string"
+ "/bulk_create_negative_keyword": {
+ "post": {
+ "tags": [
+ "negative_keyword"
+ ],
+ "description": "This method adds negative keywords, in bulk, to an existing ad group in a priority strategy campaign that uses manual targeting.
Specify the campaignId and adGroupId in the request body, along with the negativeKeywordText and negativeKeywordMatchType.
Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller.",
+ "operationId": "bulkCreateNegativeKeyword",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "A type that defines the fields for the bulk request to create negative keywords.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "A type that defines the fields for the bulk request to create negative keywords.",
+ "$ref": "#/components/schemas/BulkCreateNegativeKeywordRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkCreateNegativeKeywordResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35033": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one request is required for bulk requests."
+ },
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ad group found for ad group id {ad_group_id}."
+ },
+ "36219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The ad group with ad group id {ad_group_id} has been archived."
+ },
+ "36323": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' {negativeKeywordText} and 'negativeKeywordMatchType' {negativeKeywordMatchType} already exists for this Campaign."
+ },
+ "36330": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The provided negative keyword match type is not supported. Valid values are: {negativeKeywordMatchTypeValues}."
+ },
+ "36331": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' {negativeKeywordText} and 'negativeKeywordMatchType' {negativeKeywordMatchType} already exists for this Ad Group."
+ },
+ "36332": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' {negativeKeywordText} cannot be more than {maxNegativeKeywordTextLength} characters."
+ },
+ "36333": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' cannot be null or empty"
+ },
+ "36334": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' contains invalid characters {invalidCharacters}"
+ },
+ "36335": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You have exceeded the maximum number of negative keyword for an ad group. Only {maxSupportedNegativeKeywordNumber} Ids are supported per ad group."
+ },
+ "36336": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' {negativeKeywordText} cannot have total number of words more than {maxWordsInNegativeKeyword} words."
+ },
+ "36337": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You have exceeded the maximum number of negative keyword requests in a bulk. Only {maxSupportedNegativeKeywordRequestNumberInBulk} Ids are supported per call."
+ },
+ "36338": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "There are duplicate 'negativeKeywordText' and 'negativeKeywordMatchType' combination in this request. You must remove the duplicate(s)."
+ },
+ "36339": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Total negative keyword requests exceed the current AdGroup negative keyword capacity, which is {maxSupportedNegativeKeywordRequestNumber}."
+ },
+ "36345": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'campaignId' and 'adGroupId' are required."
+ },
+ "36346": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You have exceeded the maximum number of negative keyword for a campaign. Only {maxSupportedNegativeKeywordNumberCampaign} Ids are supported per campaign."
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This type defines the fields for the UpdateAdGroup request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the fields for the UpdateAdGroup request.",
- "$ref": "#/components/schemas/UpdateAdGroupRequest"
- }
- }
- },
- "required": true
},
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36201": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "An ad group with name {name} already exists for this campaign."
- },
- "36202": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The ad group name cannot be more than {maxAdGroupNameLength} characters."
- },
- "36203": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' value {defaultBidValue} is not valid. The default bid value should be a double precision value."
- },
- "36204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' currency {defaultBidCurrency} is not valid or missing."
- },
- "36205": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' value {defaultBidValue} is below floor value {bidFloorValue}."
- },
- "36206": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' value {defaultBidValue} is above max value {bidMaxValue}."
- },
- "36207": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' value {defaultBidValue} is more than daily budget."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No ad group found for ad group id {ad_group_id}."
- },
- "36212": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' currency {defaultBidCurrency} should be the same as the daily budget."
- },
- "36216": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' value {defaultBidValue} is not valid or missing."
- },
- "36217": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The Ad Group name contains invalid characters. {notAllowedCharacters} are not allowed."
- },
- "36224": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'defaultBid' or 'adGroupStatus' or 'name' value is required for this call."
- },
- "36225": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'ad_group_statuses' value is invalid. It should be either ACTIVE, PAUSED or ARCHIVED."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "36213": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign funding model should be CPC. Please check funding model for provided campaign id."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "/bulk_update_negative_keyword": {
+ "post": {
+ "tags": [
+ "negative_keyword"
+ ],
+ "description": "This method updates the statuses of existing negative keywords, in bulk.
Specify the negativeKeywordId and negativeKeywordStatus in the request body.",
+ "operationId": "bulkUpdateNegativeKeyword",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "A type that defines the fields for the bulk request to update negative keyword statuses.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "A type that defines the fields for the bulk request to update negative keyword statuses.",
+ "$ref": "#/components/schemas/BulkUpdateNegativeKeywordRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BulkUpdateNegativeKeywordResponse"
+ }
+ }
+ }
+ },
+ "207": {
+ "description": "Multi Status",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "36337": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You have exceeded the maximum number of negative keyword requests in a bulk. Only {maxSupportedNegativeKeywordRequestNumberInBulk} Ids are supported per call."
+ },
+ "36340": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No negative keyword found for negative keyword id {negativeKeywordId}."
+ },
+ "36341": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "There are duplicate negative keyword Ids in this request. You must remove the duplicate(s)."
+ },
+ "36342": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "NegativeKeywordStatus is missing or invalid. It is required for update."
+ },
+ "36343": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Negative keyword with negative keyword id {negativeKeywordId} is already archived and cannot be updated."
+ },
+ "36348": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Negative keyword id 'negativeKeywordId' is required."
+ },
+ "36349": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'negativeKeywordId' is invalid."
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_bids": {
- "post": {
- "tags": [
- "ad_group"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method allows sellers to retrieve the suggested bids for input keywords and match type.",
- "operationId": "suggestBids",
- "parameters": [
- {
- "name": "ad_group_id",
- "in": "path",
- "description": "The ID of the ad group containing the keywords for which the bid suggestions will be provided.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
+ "/negative_keyword": {
+ "get": {
+ "tags": [
+ "negative_keyword"
+ ],
+ "description": "This method can be used to retrieve all of the negative keywords for ad groups in priority strategy campaigns that use the Cost Per Click (CPC) funding model.
The results can be filtered using the campaign_ids, ad_group_ids, and negative_keyword_status query parameters.
Call the getCampaigns method to retrieve a list of current campaign IDs for a seller.",
+ "operationId": "getNegativeKeywords",
+ "parameters": [
+ {
+ "name": "ad_group_ids",
+ "in": "query",
+ "description": "A comma-separated list of ad group IDs.
This query parameter is used if the seller wants to retrieve the negative keywords from one or more specific ad groups. The results might not include these ad group IDs if other search conditions exclude them.
Use the getAdGroups method to retrieve the ad group IDs for a seller.
Required if the search results must be filtered to include negative keywords created at the ad group level.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "campaign_ids",
+ "in": "query",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the negative keywords being retrieved.
This query parameter is used if the seller wants to retrieve the negative keywords from a specific campaign. The results might not include these campaign IDs if other search conditions exclude them.
Note: Currently, only one campaign ID value is supported for each request.
Use the getCampaigns method to retrieve campaign IDs.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The number of results, from the current result set, to be returned in a single page.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "negative_keyword_status",
+ "in": "query",
+ "description": "A comma-separated list of negative keyword statuses.
This query parameter is used if the seller wants to filter the search results based on one or more negative keyword statuses.
See NegativeKeywordStatusEnum for supported values.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "The number of results that will be skipped in the result set. This is used with the limit field to control the pagination of the output.
For example, if the offset is set to 0 and the limit is set to 10, the method will retrieve items 1 through 10 from the list of items returned. If the offset is set to 10 and the limit is set to 10, the method will retrieve items 11 through 20 from the list of items returned.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/NegativeKeywordPagedCollectionResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35029": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
+ },
+ "35030": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'offset' cannot be less than zero."
+ },
+ "36329": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The ad group Id is required."
+ },
+ "36347": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Currently only one value is supported for 'campaign_ids'."
+ },
+ "36350": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'negative_keyword_status' is invalid."
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "post": {
+ "tags": [
+ "negative_keyword"
+ ],
+ "description": "This method adds a negative keyword to an existing ad group in a priority strategy campaign that uses manual targeting.
Specify the campaignId and adGroupId in the request body, along with the negativeKeywordText and negativeKeywordMatchType.
Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller.",
+ "operationId": "createNegativeKeyword",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "A type that defines the fields for the request to create a negative keyword.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "A type that defines the fields for the request to create a negative keyword.",
+ "$ref": "#/components/schemas/CreateNegativeKeywordRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "201": {
+ "description": "Created",
+ "headers": {
+ "Location": {
+ "schema": {
+ "type": "string",
+ "description": "The location response header contains the URI of the newly created negative keyword. The URI includes the newly created negativeKeywordId, which you can use to reference the negative keyword."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35035": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The campaign with campaign id {campaign_id} has ended."
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for campaign id {campaign_id}."
+ },
+ "36210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ad group found for ad group id {ad_group_id}."
+ },
+ "36219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The ad group with ad group id {ad_group_id} has been archived."
+ },
+ "36323": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' {negativeKeywordText} and 'negativeKeywordMatchType' {negativeKeywordMatchType} already exists for this Campaign."
+ },
+ "36330": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The provided negative keyword match type is not supported. Valid values are: {negativeKeywordMatchTypeValues}."
+ },
+ "36331": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' {negativeKeywordText} and 'negativeKeywordMatchType' {negativeKeywordMatchType} already exists for this Ad Group."
+ },
+ "36332": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' {negativeKeywordText} cannot be more than {maxNegativeKeywordTextLength} characters."
+ },
+ "36333": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' cannot be null or empty"
+ },
+ "36334": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' contains invalid characters {invalidCharacters}"
+ },
+ "36335": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You have exceeded the maximum number of negative keyword for an ad group. Only {maxSupportedNegativeKeywordNumber} Ids are supported per ad group."
+ },
+ "36336": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'negativeKeywordText' {negativeKeywordText} cannot have total number of words more than {maxWordsInNegativeKeyword} words."
+ },
+ "36345": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'campaignId' and 'adGroupId' are required."
+ },
+ "36346": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You have exceeded the maximum number of negative keyword for a campaign. Only {maxSupportedNegativeKeywordNumberCampaign} Ids are supported per campaign."
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This method is not supported for campaigns with smart targeting type."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
- ],
- "requestBody": {
- "description": "The data requested to retrieve the suggested bids.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The data requested to retrieve the suggested bids.",
- "$ref": "#/components/schemas/TargetedBidRequest"
- }
+ },
+ "/negative_keyword/{negative_keyword_id}": {
+ "get": {
+ "tags": [
+ "negative_keyword"
+ ],
+ "description": "This method retrieves details on a specific negative keyword.
In the request, specify the negative_keyword_id as a path parameter.",
+ "operationId": "getNegativeKeyword",
+ "parameters": [
+ {
+ "name": "negative_keyword_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique identifier for the negative keyword being retrieved.
Use the getNegativeKeywords method to retrieve negative keyword IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/NegativeKeyword"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "36340": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No negative keyword found for negative keyword id {negativeKeywordId}."
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "put": {
+ "tags": [
+ "negative_keyword"
+ ],
+ "description": "This method updates the status of an existing negative keyword.
Specify the negative_keyword_id as a path parameter, and specify the negativeKeywordStatus in the request body.",
+ "operationId": "updateNegativeKeyword",
+ "parameters": [
+ {
+ "name": "negative_keyword_id",
+ "in": "path",
+ "description": "The unique identifier for the negative keyword.
This value is returned in the Location response header from the createNegativeKeyword method.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "A type that defines the fields for the request to update a negative keyword.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "A type that defines the fields for the request to update a negative keyword.",
+ "$ref": "#/components/schemas/UpdateNegativeKeywordRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "36340": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No negative keyword found for negative keyword id {negativeKeywordId}."
+ },
+ "36342": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "NegativeKeywordStatus is missing or invalid. It is required for update."
+ },
+ "36343": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Negative keyword with negative keyword id {negativeKeywordId} is already archived and cannot be updated."
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "required": true
},
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/TargetedBidsPagedCollection"
- }
- }
+ "/ad_report/{report_id}": {
+ "get": {
+ "tags": [
+ "ad_report"
+ ],
+ "description": "This call downloads the report as specified by the report_id path parameter.
Call createReportTask to schedule and generate a Promoted Listings report. All date values are returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).
Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Use the getReportTasks method to retrieve report IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "text/tab-separated-values": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35110": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'report_id' {report_id} was not found. Correct the 'report_id' and try the call again."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35041": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'marketplaceId' is required."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "35091": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You have exceeded the maximum number of requests. Only {maxSupportedNumber} are supported per call."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No ad group found for ad group id {ad_group_id}."
- },
- "36301": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The provided keyword match type is not supported. Valid values are: {matchTypeValues}."
- },
- "36304": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keywordText {keywordText} cannot be more than {maxKeywordTextLength} characters."
- },
- "36311": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keywordText cannot be null or empty."
- },
- "36312": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keywordText contains invalid characters {invalidCharacters}"
- }
- }
+ },
+ "/ad_report_metadata": {
+ "get": {
+ "tags": [
+ "ad_report_metadata"
+ ],
+ "description": "This call retrieves information that details the fields used in each of the Promoted Listings reports. Use the returned information to configure the different types of Promoted Listings reports. You can retrieve metadata for all report types,funding models and channels, or you can filter based on funding model and/or channel.
Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged.",
+ "operationId": "getReportMetadata",
+ "parameters": [
+ {
+ "name": "funding_model",
+ "in": "query",
+ "description": "This query parameter is used only if the user wants to see report metadata for a specific funding model. Refer to the FundingModelEnum type for supported values.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "channel",
+ "in": "query",
+ "description": "This query parameter is used only if the user wants to see COST_PER_CLICK report metadata for a specific channel. Refer to the ChannelEnum type for supported values.
Note: The channel parameter is only applicable for COST_PER_CLICK funding model.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ReportMetadatas"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35121": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'fundingModel' is invalid. Valid values are: {supportedFundingModels}."
+ },
+ "35125": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'channel' is invalid. Valid values are: {supportedChannels}."
+ },
+ "35127": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'channels' are not supported for the 'fundingModel' {fundingModel}."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35051": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}."
- },
- "36320": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The keywordText {keywordText} cannot have total number of words more than {maxWordsInKeyword} words"
- }
- }
+ },
+ "/ad_report_metadata/{report_type}": {
+ "get": {
+ "tags": [
+ "ad_report_metadata"
+ ],
+ "description": "This call retrieves metadata that details the fields used by a specific Promoted Listings report type. Use the report_type path parameter to indicate metadata to retrieve.
This method does not use a request payload.
Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged.",
+ "operationId": "getReportMetadataForReportType",
+ "parameters": [
+ {
+ "name": "report_type",
+ "in": "path",
+ "description": "This path parameter specifies the name of the report type whose metadata you want to retrieve.
For details about available report types and their descriptions, refer to the ReportTypeEnum.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "funding_model",
+ "in": "query",
+ "description": "The funding model used in the report. The funding model must be compatible with the report type specified in the path parameter. Refer to the FundingModelEnum type for supported values.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "channel",
+ "in": "query",
+ "description": "The channel used in the report. The channel must be compatible with the report type specified in the path parameter. Refer to the ChannelEnum type for supported values.
Note: The channel parameter is only applicable for COST_PER_CLICK funding model.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ReportMetadata"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35116": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Supplied 'report_type' not found. Valid values are: {supportedReportTypes}."
+ },
+ "35121": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'fundingModel' is invalid. Valid values are: {supportedFundingModels}."
+ },
+ "35125": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'channel' is invalid. Valid values are: {supportedChannels}."
+ },
+ "35127": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'channels' are not supported for the 'fundingModel' {fundingModel}."
+ },
+ "35132": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'channels' {supportedChannels} are not supported for the 'report_type' {reportType}."
+ },
+ "35133": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'fundingModel' is not supported for the 'report_type' {reportType}."
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You are currently not authorized to access the Promoted Listings Advanced program. Please contact support."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
+ },
+ "/ad_report_task": {
+ "get": {
+ "tags": [
+ "ad_report_task"
+ ],
+ "description": "This method returns information on all the existing report tasks related to a seller. Use the report_task_statuses query parameter to control which reports to return. You can paginate the result set by specifying a limit, which dictates how many report tasks to return on each page of the response. Use the offset parameter to specify how many reports to skip in the result set before returning the first result.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Default: 10
Maximum: 500",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "Specifies the number of report tasks to skip in the result set before returning the first report in the paginated response. Combine offset with the limit query parameter to control the reports returned in the response. For example, if you supply an offset of 0 and a limit of 10, the response contains the first 10 reports from the complete list of report tasks retrieved by the call. If offset is 10 and limit is 10, the first page of the response contains reports 11-20 from the complete result set.
Default: 0",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "report_task_statuses",
+ "in": "query",
+ "description": "This query parameter filters the returned report tasks by their status. Supply a comma-separated list of the report statuses you want returned. The results are filtered to include only the report statuses you specify.
Note: The results might not include some report tasks if other search conditions exclude them.
See TaskStatusEnum for supported values.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ReportTaskPagedCollection"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35029": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
+ },
+ "35030": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'offset' cannot be less than zero {offset}."
+ },
+ "35109": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'report_task_statuses' {invalid_report_task_statuses} is invalid. Valid values are: {supportedReportTaskStatuses}."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "post": {
+ "tags": [
+ "ad_report_task"
+ ],
+ "description": "This method creates a report task, which generates a Promoted Listings report based on the values specified in the call.
The report is generated based on the criteria you specify, including the report type, the report's dimensions and metrics, the report's start and end dates, the listings to include in the report, and more. Metrics are the quantitative measurements in the report while dimensions specify the attributes of the data included in the reports.
When creating a report task, you can specify the items you want included in the report. The items you specify, using either listingId or inventoryReference values, must be in a Promoted Listings campaign for them to be included in the report.
For details on the required and optional fields for each report type, see Promoted Listings reporting.
This call returns the URL to the report task in the Location response header, and the URL includes the report-task ID.
Reports often take time to generate and it's common for this call to return an HTTP status of 202, which indicates the report is being generated. Call getReportTasks (or getReportTask with the report-task ID) to determine the status of a Promoted Listings report. When a report is complete, eBay sets its status to SUCCESS and you can download it using the URL returned in the reportHref field of the getReportTask call. Report files are tab-separated value gzip files with a file extension of .tsv.gz.
Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged.
Note: This call fails if you don't submit all the required fields for the specified report type. Fields not supported by the specified report type are ignored. Call getReportMetadata to retrieve a list of the fields you need to configure for each Promoted Listings report type.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Important! The data threshold for a single report is currently 1 million records; if this threshold is exceeded, the report will fail.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "The container for the fields that define the report task.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "The container for the fields that define the report task.",
+ "$ref": "#/components/schemas/CreateReportTask"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "202": {
+ "description": "Accepted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35012": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'inventoryReferenceId' {inventoryReferenceId} is not valid."
+ },
+ "35013": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'listingId' {listingId} is not valid. Correct the 'listingId' and try the call again."
+ },
+ "35040": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'inventoryReferenceType' {inventoryReferenceType} is not supported."
+ },
+ "35041": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A 'marketplaceId' is required. Supported marketplaces are: {supportedMarketplaces}"
+ },
+ "35045": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No campaign found for {campaignId}."
+ },
+ "35090": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "dateFrom and dateTo span exceeds maximum allowed. Only up to {maxDayRange} days are supported."
+ },
+ "35100": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Campaign ID is required for this call."
+ },
+ "35102": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The {date_key} date is required for this call."
+ },
+ "35103": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The date cannot be in future."
+ },
+ "35104": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The report start date {dateFrom} cannot be after the end date {dateTo}."
+ },
+ "35105": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The report 'dateFrom' {dateFrom} is out of range. Reports are limited up to {maxDays} days in the past."
+ },
+ "35106": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'dimensionKey' {dimensionKey} is not valid. To see the supported dimension keys for a report, use one of the 'Get Metadata' calls."
+ },
+ "35107": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'dimensionKey' {dimensionKey} is not supported for the 'reportType' {reportType}. To see the supported dimension keys for a report, use one of the 'Get Metadata' calls."
+ },
+ "35108": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'annotationKey' {annotationKey} is not supported for the 'dimensionKey' {dimensionKey}. To see the supported annotation and dimension keys for a report, use one of the 'Get Metadata' calls."
+ },
+ "35111": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'inventoryReferenceId' {inventoryReferenceId} is not valid."
+ },
+ "35113": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID is required for this call."
+ },
+ "35114": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'reportType' is invalid. Valid values are: {supportedReportTypes}."
+ },
+ "35115": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'metricKey' {metricKey} is not supported for the 'reportType' {reportType}. To see the supported metric keys for a report, use one of the 'Get Metadata' calls."
+ },
+ "35118": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'reportFormat' is missing or invalid. Valid values are: {supportedReportFormats}"
+ },
+ "35119": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The minimum set of 'dimensionKey' is not provided for the 'reportType' {reportType}. Minimum required dimensionKeys are: {minimumDimensionKeys}"
+ },
+ "35120": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one 'metricKey' must be provided for 'reportType' {reportType}. Valid metricKeys are: {supportedMetricKeys}"
+ },
+ "35121": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'fundingModel' is invalid. Valid values are: {supportedFundingModels}."
+ },
+ "35122": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The metric key is not supported for the funding model."
+ },
+ "35123": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'dimensionKey' {dimensionKey} is not valid for the 'fundingModel' {fundingModel}"
+ },
+ "35124": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Multiple funding models are not supported. Please use one of the following funding models: {supportedFundingModels}"
+ },
+ "35125": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'channel' is invalid. Valid values are: {supportedChannels}."
+ },
+ "35126": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Multiple channels are not supported. Please use one of the following channels: {supportedChannels}"
+ },
+ "35127": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'channels' are not supported for the 'fundingModel' {fundingModel}"
+ },
+ "35128": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'dimensionKey' {dimensionKey} is not valid for the 'channels' {supportedChannels}"
+ },
+ "35129": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'metricKey' {metricKey} is not supported for the 'channels' {supportedChannels}"
+ },
+ "35130": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'annotationKey' {annotationKey} is not supported for the 'fundingModel' {fundingModel}."
+ },
+ "35131": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'annotationKey' {annotationKey} is not supported for the 'channels' {supportedChannels}"
+ },
+ "35137": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The {date_key} date format is not valid."
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35089": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You are currently not authorized to access the Promoted Listings Advanced program. Please contact support"
+ },
+ "35091": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'additionalRecords' are supported only with COST_PER_CLICK FundingModel and non-performing data is applicable for account level reports with no Day level dimension. 'additionalRecords' are applicable for reportTypes {supportedReportTypes}"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35051": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'marketplaceId' {marketplaceId} is not supported. Supported marketplaces are: {supportedMarketplaces}"
+ },
+ "35068": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of listing IDs. Only {maxSupportedListings} listings are supported per call."
+ },
+ "35101": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You have exceeded the maximum number of campaign IDs. Only {maxSupportedCampaigns} campaigns are supported per call."
+ },
+ "35112": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The maximum number {maxSupportedInventoryReferences} of inventory references has been exceeded."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_keywords": {
- "post": {
- "tags": [
- "ad_group"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method allows sellers to retrieve a list of keyword ideas to be targeted for Promoted Listings campaigns.",
- "operationId": "suggestKeywords",
- "parameters": [
- {
- "name": "ad_group_id",
- "in": "path",
- "description": "The ID of the ad group for which the keyword suggestions will be provided.",
- "required": true,
- "schema": {
- "type": "string"
+ "/ad_report_task/{report_task_id}": {
+ "get": {
+ "tags": [
+ "ad_report_task"
+ ],
+ "description": "This call returns the details of a specific Promoted Listings report task, as specified by the report_task_id path parameter. The report task includes the report criteria (such as the report dimensions, metrics, and included listing) and the report-generation rules (such as starting and ending dates for the specified report task).
Report-task IDs are generated by eBay when you call createReportTask. Get a complete list of a seller's report-task IDs by calling getReportTasks.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Use the getReportTasks method to retrieve report task Ids.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ReportTask"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35140": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ReportTask found for 'report_task_id' {report_task_id}. Please correct the 'report_task_id' and try again."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "delete": {
+ "tags": [
+ "ad_report_task"
+ ],
+ "description": "This call deletes the report task specified by the report_task_id path parameter. This method also deletes any reports generated by the report task. Report task IDs are generated by eBay when you call createReportTask. Get a complete list of a seller's report-task IDs by calling getReportTasks.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Use the getReportTasks method to retrieve report task Ids.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35140": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "No ReportTask found for 'report_task_id' {report_task_id}. Please correct the 'report_task_id' and try again."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35141": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The Report Task with 'report_task_id' {report_task_id} is being modified. Please wait a few minutes and try the call again."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
+ },
+ "/item_price_markdown": {
+ "post": {
+ "tags": [
+ "item_price_markdown"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method creates an item price markdown discount (know simply as a \"markdown discount\") where a discount amount is applied directly to the items included in the discount. Discounts can be specified as either a monetary amount or a percentage off the standard sales price. eBay highlights discounted items by placing teasers for the items throughout the online sales flows. Unlike an item discount, a markdown discount does not require the buyer meet a \"threshold\" before the offer takes effect. With markdown discounts, all the buyer needs to do is purchase the item to receive the discount benefit.
Important: There are some restrictions for which listings are available for price markdown discounts. For details, see Discounts Manager requirements and restrictions.
In addition, we recommend you list items at competitive prices before including them in your markdown discounts. For an extensive list of pricing recommendations, see the Growth tab in Seller Hub.
There are two ways to enable items for markdown discounts:
- Key-based discounts select items using either the listing IDs or inventory reference IDs of the items you want to discount. Note that if you use inventory reference IDs, you must specify both the inventoryReferenceId and the associated inventoryReferenceType of the item(s) you want to include.
- Rule-based discounts select items using a list of eBay category IDs or seller Store category IDs. Rules can further constrain items being discounted by minimum and maximum prices, brands, and item conditions.
New discounts must be created in either a DRAFT or a SCHEDULED state. Use the DRAFT state when you are initially creating a discount and you want to be sure it's correctly configured before scheduling it to run. When you create a discount, the promotionId is returned in the Location response header. Use this ID to reference the discount in subsequent requests (such as to schedule a discount that's in a DRAFT state).
Tip: Refer to Discounts Manager in the Selling Integration Guide for details and examples showing how to create and manage seller discounts.
Markdown discounts are available on all eBay marketplaces. For more information, see Discounts Manager requirements and restrictions.
",
+ "operationId": "createItemPriceMarkdownPromotion",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the fields that describe an item price markdown discount.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields that describe an item price markdown discount.",
+ "$ref": "#/components/schemas/ItemPriceMarkdown"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "201": {
+ "description": "Created",
+ "headers": {
+ "Location": {
+ "schema": {
+ "type": "string",
+ "description": "The location response header contains the URL to the newly created item price markdown discount. The URL includes the eBay-assigned promotionId, which you can use to reference the discount."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38226": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID must be numeric if you're using listingIds."
+ },
+ "38227": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID is invalid."
+ },
+ "38263": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}."
+ },
+ "38272": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This listing is not eligible for a promotion because it's an auction-style listing."
+ },
+ "38273": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing."
+ },
+ "38274": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You haven't included electronic payment method as a payment method. In order to make this listing eligible, update it to include electronic payment method."
+ },
+ "38275": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This SKU used in inventoryReferenceId matches an item that is part of a listing with variations. This SKU is only eligible if we add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label)."
+ },
+ "345112": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid Store category. Please refer to API documentation to source allowed values."
+ },
+ "345113": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid marketplace category ID. Please refer to API documentation for the supported values."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "38218": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A valid entry is required for {fieldName}."
+ },
+ "38219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The start date and time must be earlier than the end date and time."
+ },
+ "38220": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The end date and time must be later than the current date and time."
+ },
+ "38228": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The amount value of '{fieldName}' contains decimals, only integers are supported."
+ },
+ "38229": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The start date and time should be later than the current date and time."
+ },
+ "38234": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "HTML is not allowed in the '{fieldName}' field."
+ },
+ "38235": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the '{fieldName}' field. For help, see the documentation for this call."
+ },
+ "38238": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountBenefit' data is missing, which is required by this call. For help, see the documentation for this call."
+ },
+ "38240": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
+ },
+ "38242": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'."
+ },
+ "38255": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion description exceeds the maximum length, which is {promoDescriptionLength}."
+ },
+ "38256": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion name exceeds the maximum length, which is {promoNameLength}."
+ },
+ "38261": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Promotions are currently limited to a maximum of {maxListingInclLimit} parent items, when entering item IDs or choosing from live inventory."
+ },
+ "38262": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can only include up to {maxSkuInclLimit} SKUs or custom labels in inventoryItems."
+ },
+ "38270": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The currency type does not match what is used for the Marketplace ID submitted."
+ },
+ "345056": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these field types: 'inventoryItems' or 'listingIds'."
+ },
+ "345057": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these fields: 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call."
+ },
+ "345058": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "When using multiple selectedInventoryDiscounts containers, each must have a unique percentageoffitems value. For help, see the documentation for this call."
+ },
+ "345059": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "If using percentageoffitems you can have between 1 and 10 selectedInventoryDiscounts containers. For help, see the documentation for this call."
+ },
+ "345060": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "If using amountoffitems you can only have selectedInventoryDiscounts container. For help, see the documentation for this call."
+ },
+ "345061": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The discount ID value is a read only value."
+ },
+ "345063": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Priority is not supported for the item_price_markdown calls."
+ },
+ "345110": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only one of Inventory Items, Listing IDs or Rules in the Inventory Criterion."
+ },
+ "345111": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify Rules when using the Inventory by Value Criterion."
+ },
+ "345114": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A Category scope is required for the Rule. Please refer to API documentation for allowed values."
+ },
+ "345115": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one Category is required. Please provide a valid input for this field and try again."
+ },
+ "345116": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only Marketplace categories or Store categories when creating Rules."
+ },
+ "345120": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid Item condition. Please refer to API documentation for allowed values."
+ },
+ "345121": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion."
+ },
+ "345122": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "category ids cannot be specified with the inventory of type any."
+ },
+ "345123": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "brands cannot be specified with inventory of type any or Store."
+ },
+ "345125": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify a child Marketplace Category ID when the parent Marketplace Category ID is already specified. Please refer to the API documentation to source allowed values."
+ },
+ "345126": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify a child Store Category ID when the parent Store Category ID is already specified. Please refer to the API documentation to source allowed values."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38248": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'percentOffItem' value is invalid. For help, see the documentation for this call."
+ },
+ "38250": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'amountOffItem' value is invalid. For help, see the documentation for this call."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
+ },
+ "/item_price_markdown/{promotion_id}": {
+ "get": {
+ "tags": [
+ "item_price_markdown"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method returns the complete details of the item price markdown discount that's indicated by the promotion_id path parameter.
Call getPromotions to retrieve the IDs of a seller's discounts.",
+ "operationId": "getItemPriceMarkdownPromotion",
+ "parameters": [
+ {
+ "name": "promotion_id",
+ "in": "path",
+ "description": "This path parameter takes a concatenation of the ID of the discount you want to retrieve plus the marketplace ID on which the discount is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the discount (promotionId) is a unique eBay-assigned value that's generated when the discount is created. The Marketplace ID is the ENUM value of eBay marketplace where the discoun is hosted.
Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.
Example: 1********5@EBAY_US",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ItemPriceMarkdown"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38203": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Resource not found. Check the ID and try the call again."
+ },
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "put": {
+ "tags": [
+ "item_price_markdown"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method updates the specified item price markdown discount with the new configuration that you supply in the payload of the request. Specify the discount you want to update using the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's discounts.
When updating a discount, supply all the fields that you used to configure the original discount (and not just the fields you are updating). eBay replaces the specified discount with the values you supply in the update request and if you don't pass a field that currently has a value, the update request fails.
The parameters you are allowed to update with this request depend on the status of the discount you're updating: - DRAFT or SCHEDULED discounts: You can update any of the parameters in these discounts that have not yet started to run, including the discountRules.
- RUNNING discounts: You can change the endDate and the item's inventory but you cannot change the discount or the start date.
- ENDED discounts: Nothing can be changed.
",
+ "operationId": "updateItemPriceMarkdownPromotion",
+ "parameters": [
+ {
+ "name": "promotion_id",
+ "in": "path",
+ "description": "This path parameter takes a concatenation of the ID of the discount you want to update plus the marketplace ID on which the discount is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the discount (promotionId) is a unique eBay-assigned value that's generated when the discount is created. The Marketplace ID is the ENUM value of eBay marketplace where the discount is hosted.
Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.
Example: 1********5@EBAY_US",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the fields that describe an item price markdown discount.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields that describe an item price markdown discount.",
+ "$ref": "#/components/schemas/ItemPriceMarkdown"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38226": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID must be numeric if you're using listingIds."
+ },
+ "38227": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID is invalid."
+ },
+ "38263": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}."
+ },
+ "38272": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This listing is not eligible for a promotion because it's an auction-style listing."
+ },
+ "38273": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing."
+ },
+ "38274": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You haven't included electronic payment method as a payment method. In order to make this listing eligible, update it to include electronic payment method."
+ },
+ "38275": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This SKU used in inventoryReferenceId matches an item that is part of a listing with variations. This SKU is only eligible if we add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label)."
+ },
+ "345064": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You have moved inventory between discountBenefit containers or have the same inventory in multiple discountBenefit containers. For help, see the documentation for this call."
+ },
+ "345112": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid Store category. Please refer to API documentation to source allowed values."
+ },
+ "345113": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid marketplace category ID. Please refer to API documentation for the supported values."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38203": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Resource not found. Check the ID and try the call again."
+ },
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "38218": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A valid entry is required for {fieldName}."
+ },
+ "38219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The start date and time must be earlier than the end date and time."
+ },
+ "38220": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The end date and time must be later than the current date and time."
+ },
+ "38225": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update a promotion that has ended."
+ },
+ "38228": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The amount value of '{fieldName}' contains decimals, only integers are supported."
+ },
+ "38229": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The start date and time should be later than the current date and time."
+ },
+ "38232": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update the promotion discount for an active promotion."
+ },
+ "38234": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "HTML is not allowed in the '{fieldName}' field."
+ },
+ "38235": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the '{fieldName}' field. For help, see the documentation for this call."
+ },
+ "38238": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountBenefit' data is missing, which is required by this call. For help, see the documentation for this call."
+ },
+ "38240": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
+ },
+ "38242": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'."
+ },
+ "38255": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion description exceeds the maximum length, which is {promoDescriptionLength}."
+ },
+ "38256": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion name exceeds the maximum length, which is {promoNameLength}."
+ },
+ "38260": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "To update the start date of a promotion, the promotion must be in draft or scheduled state."
+ },
+ "38261": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Promotions are currently limited to a maximum of {maxListingInclLimit} parent items, when entering item IDs or choosing from live inventory."
+ },
+ "38262": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can only include up to {maxSkuInclLimit} SKUs or custom labels in inventoryItems."
+ },
+ "38269": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion ID does not match any of the seller's promotions."
+ },
+ "38270": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The currency type does not match what is used for the Marketplace ID submitted."
+ },
+ "345056": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these field types: 'inventoryItems' or 'listingIds'."
+ },
+ "345057": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these fields: 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call."
+ },
+ "345058": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "When using multiple selectedInventoryDiscounts containers, each must have a unique percentageoffitems value. For help, see the documentation for this call."
+ },
+ "345059": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "If using percentageoffitems you can have between 1 and 10 selectedInventoryDiscounts containers. For help, see the documentation for this call."
+ },
+ "345060": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "If using amountoffitems you can only have selectedInventoryDiscounts container. For help, see the documentation for this call."
+ },
+ "345061": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The discount ID value is a read only value."
+ },
+ "345063": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Priority is not supported for the item_price_markdown calls."
+ },
+ "345065": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot change the status of aa SCHEDULED promotion to DRAFT. For help, see the documentation for this call."
+ },
+ "345070": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The giving discount ID does not exist in the promotion. For help, see the documentation for this call."
+ },
+ "345071": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The giving discount type is not consistent with existing active promotion. For help, see the documentation for this call."
+ },
+ "345072": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The giving inventory criterion type is not consistent with existing active promotion. For help, see the documentation for this call."
+ },
+ "345110": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only one of Inventory Items, Listing IDs or Rules in the Inventory Criterion."
+ },
+ "345111": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify Rules when using the Inventory by Value Criterion."
+ },
+ "345114": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A Category scope is required for the Rule. Please refer to API documentation for allowed values."
+ },
+ "345115": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one Category is required. Please provide a valid input for this field and try again."
+ },
+ "345116": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only Marketplace categories or Store categories when creating Rules."
+ },
+ "345120": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid Item condition. Please refer to API documentation for allowed values."
+ },
+ "345121": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify Rules or inventory items when using the Inventory by ALL Criterion."
+ },
+ "345122": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "category ids cannot be specified with the inventory of type any."
+ },
+ "345123": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "brands cannot be specified with inventory of type any or Store."
+ },
+ "345125": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify a child Marketplace Category ID when the parent Marketplace Category ID is already specified. Please refer to the API documentation to source allowed values."
+ },
+ "345126": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify a child Store Category ID when the parent Store Category ID is already specified. Please refer to the API documentation to source allowed values."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38248": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'percentOffItem' value is invalid. For help, see the documentation for this call."
+ },
+ "38250": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'amountOffItem' value is invalid. For help, see the documentation for this call."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, please contact support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "delete": {
+ "tags": [
+ "item_price_markdown"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method deletes the item price markdown discount specified by the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's discounts.
You can delete any discount with the exception of those that are currently active (RUNNING). To end a running discount, call updateItemPriceMarkdownPromotion and adjust the endDate field as appropriate.",
+ "operationId": "deleteItemPriceMarkdownPromotion",
+ "parameters": [
+ {
+ "name": "promotion_id",
+ "in": "path",
+ "description": "This path parameter takes a concatenation of the ID of the discount you want to delete plus the marketplace ID on which the discount is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the discount (promotionId) is a unique eBay-assigned value that's generated when the discount is created. The Marketplace ID is the ENUM value of eBay marketplace where the discount is hosted.
Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.
Example: 1********5@EBAY_US",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38203": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Resource not found. Check the ID and try the call again."
+ },
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "345067": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A promotion can only be deleted if it is ended."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, please contact support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
- ],
- "requestBody": {
- "description": "The required data to retrieve suggested keywords.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The required data to retrieve suggested keywords.",
- "$ref": "#/components/schemas/TargetedKeywordRequest"
- }
+ },
+ "/item_promotion": {
+ "post": {
+ "tags": [
+ "item_promotion"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method creates an item discount, where the buyer receives a discount when they meet the specific buying criteria. Known here as \"threshold discounts\", these discounts trigger when a threshold is met. eBay highlights discounted items by placing teasers for the discounted items throughout the online buyer flows.
Discounts are specified as either a monetary amount or a percentage off the standard sales price of a listing, letting you offer deals such as \"Buy 1 Get 1\" and \"Buy $50, get 20% off\".
Volume pricing discounts increase the value of the discount as the buyer increases the quantity they purchase.
Coded Coupons provide unique codes that a buyer can use during checkout to receive a discount. The seller can specify the number of times a buyer can use the coupon and the maximum amount across all purchases that can be discounted using the coupon. The coupon code can also be made public (appearing on the seller's Offer page, search pages, the item listing, and the checkout page) or private (only on the seller's Offer page, but the seller can include the code in email and social media).
Note: Coded Coupons are currently available in the US, UK, DE, FR, IT, ES, and AU marketplaces.
There are two ways to add items to a threshold discount:
- Key-based discounts select items using either the listing IDs or inventory reference IDs of the items you want to discount. Note that if you use inventory reference IDs, you must specify both the inventoryReferenceId and the associated inventoryReferenceType of the item(s) you want to be discounted.
- Rule-based discounts select items using a list of eBay category IDs or seller Store category IDs. Rules can further constrain the items being discounted by minimum and maximum prices, brands, and item conditions.
You must create a new discount in either a DRAFT or SCHEDULED state. Use the DRAFT state when you are initially creating a discount and you want to be sure it's correctly configured before scheduling it to run. When you create a discount, the promotion ID is returned in the Location response header. Use this ID to reference the discount in subsequent requests.
Tip: Refer to the Selling Integration Guide for details and examples showing how to create and manage threshold discounts using the Discounts Manager.
For information on the eBay marketplaces that support item discounts, see Discounts Manager requirements and restrictions.
",
+ "operationId": "createItemPromotion",
+ "parameters": [
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the fields that describe an item discount.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields that describe an item discount.",
+ "$ref": "#/components/schemas/ItemPromotion"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "201": {
+ "description": "Created",
+ "headers": {
+ "Location": {
+ "schema": {
+ "type": "string",
+ "description": "URL location of new item promotion."
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BaseResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38226": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID must be numeric if you're using listingIds."
+ },
+ "38227": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID is invalid."
+ },
+ "38263": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}."
+ },
+ "38272": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This listing is not eligible for a promotion because it's an auction-style listing."
+ },
+ "38273": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing."
+ },
+ "38274": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You haven't included electronic payment method as a payment method. In order to make this listing eligible, update it to include electronic payment method."
+ },
+ "38275": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This SKU used in inventoryReferenceId matches an item that is part of a listing with variations. This SKU is only eligible if you add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label)."
+ },
+ "345112": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid Store category. Please refer to API documentation to source allowed values."
+ },
+ "345113": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid marketplace category ID. Please refer to API documentation for the supported values."
+ },
+ "345137": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'priority' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345138": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'description' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345139": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'applyDiscountToSingleItemOnly' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345140": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'promotionImageUrl' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345142": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'applyDiscountToSingleItemOnly' is currently not supported for this Marketplace ID. For help, see the documentation for this call."
+ },
+ "345143": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'couponType' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345144": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'maxCouponRedemptionPerUser' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345145": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'maxDiscountAmount' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345146": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'budget' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345147": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'couponCode' can not be set for this promotion type. For help, see the documentation for this call."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "38205": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The Marketplace ID is not recognized or is not eligible for promotions."
+ },
+ "38207": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion priority is invalid. Please check and try the call again."
+ },
+ "38218": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A valid entry is required for {fieldName}."
+ },
+ "38219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The start date and time must be earlier than the end date and time."
+ },
+ "38220": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The end date and time must be later than the current date and time."
+ },
+ "38228": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The amount value of '{fieldName}' contains decimals, only integers are supported."
+ },
+ "38229": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The start date and time should be later than the current date and time."
+ },
+ "38234": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "HTML is not allowed in the '{fieldName}' field."
+ },
+ "38235": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the '{fieldName}' field. For help, see the documentation for this call."
+ },
+ "38236": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountSpecification' data is missing, which is required by this call. For help, see the documentation for this call."
+ },
+ "38237": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these fields: 'minQuantity', 'forEachQuantity', 'minAmount', or 'forEachAmount' in 'discountSpecification'. For help, see the documentation for this call."
+ },
+ "38238": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountBenefit' data is missing, which is required by this call. For help, see the documentation for this call."
+ },
+ "38239": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these fields: 'percentageOffOrder', 'amountOffOrder', 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call."
+ },
+ "38240": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
+ },
+ "38241": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This discount rule combination is currently not supported. For help, see the documentation for this call."
+ },
+ "38242": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'."
+ },
+ "38253": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The data combination of 'DiscountSpecification' and 'DiscountBenefit' is not valid for this promotion type. For help, see the documentation for this call."
+ },
+ "38255": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion description exceeds the maximum length, which is {promoDescriptionLength}."
+ },
+ "38256": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion name exceeds the maximum length, which is {promoNameLength}."
+ },
+ "38257": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This promotion type supports only one discount rule for the item promotion."
+ },
+ "38260": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "To update the start date of a promotion, the promotion must be in draft or scheduled state."
+ },
+ "38261": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Promotions are currently limited to a maximum of {maxListingInclLimit} parent items, when entering item IDs or choosing from live inventory."
+ },
+ "38262": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can only include up to {maxSkuInclLimit} SKUs or custom labels in inventoryItems."
+ },
+ "38265": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Number of discount items is greater than the quantity specified in 'DiscountSpecification'."
+ },
+ "38267": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'DiscountBenefit.amountOffOrder' field cannot be used with the 'DiscountSpecification.numberOfDiscountedItems' field. This parameter is reserved for Buy x, Get x discounts. For help, see the documentation for this call."
+ },
+ "345110": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only one of Inventory Items, Listing IDs or Rules in the Inventory Criterion."
+ },
+ "345111": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify Rules when using the Inventory by Value Criterion."
+ },
+ "345114": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A Category scope is required for the Rule. Please refer to API documentation for allowed values."
+ },
+ "345115": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one Category is required. Please provide a valid input for this field and try again."
+ },
+ "345116": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only Marketplace categories or Store categories when creating Rules."
+ },
+ "345118": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion."
+ },
+ "345120": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid Item condition. Please refer to API documentation for allowed values."
+ },
+ "345121": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion."
+ },
+ "345122": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "category ids cannot be specified with the inventory of type any."
+ },
+ "345123": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "brands cannot be specified with inventory of type any or Store."
+ },
+ "345124": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Exclusions are currently limited to a maximum of 100 parent items, when entering Inventory Items or Listing IDs, or choosing from live inventory."
+ },
+ "345125": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify a child Marketplace Category ID when the parent Marketplace Category ID is already specified. Please refer to the API documentation to source allowed values."
+ },
+ "345126": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify a child Store Category ID when the parent Store Category ID is already specified. Please refer to the API documentation to source allowed values."
+ },
+ "345127": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Category aspects are not supported in this version."
+ },
+ "345128": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The minimum discount rules required for volume discount promotions are {numOfDiscountRules}"
+ },
+ "345129": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountRules.ruleOrder' is missing or invalid for one of the discount rules for volume discount promotions. see the documentation for this call."
+ },
+ "345130": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can include up to a maximum of {numOfDiscountRules} discount rules in a volume discount promotion."
+ },
+ "345131": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Each 'minQuantity' value should be one greater than the 'minQuantity' value of the previous discount rule."
+ },
+ "345132": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The discount value is invalid for one of the discount rules for volume discount promotions. see the documentation for this call."
+ },
+ "345133": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Each 'percentageOffOrder' or 'amountOffOrder' value should be greater than the 'percentageOffOrder' or 'amountOffOrder' value of the previous discount rule for volume discount promotions."
+ },
+ "345134": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This promotionType is currently not supported. For help, see the documentation for this call."
+ },
+ "345136": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountBenefit' specified is not supported for this promotion Type. For help, see the documentation for this call."
+ },
+ "345137": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'couponCode' data is missing for coded coupon promotions. For help, see the documentation for this call."
+ },
+ "345138": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'couponCode' value is invalid. For help, see the documentation for this call."
+ },
+ "345139": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'couponType' data is missing for coded coupon promotions. For help, see the documentation for this call."
+ },
+ "345140": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'couponType' value is invalid. For help, see the documentation for this call."
+ },
+ "345141": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxDiscountAmount' data is missing for coded coupon promotions. For help, see the documentation for this call."
+ },
+ "345142": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxDiscountAmount' value is invalid. For help, see the documentation for this call."
+ },
+ "345143": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCouponRedemptionPerUser' value is invalid. For help, see the documentation for this call."
+ },
+ "345144": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'budget' value is invalid. For help, see the documentation for this call."
+ },
+ "345145": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A coupon with this 'couponCode' already exists. Please try a different 'couponCode'."
+ },
+ "345146": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'currency' for 'maxDiscountAmount' and 'budget' has to be same. For help, see the documentation for this call."
+ },
+ "345147": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'promotionType' CODED_COUPON is currently not supported for this Marketplace ID. For help, see the documentation for this call."
+ },
+ "345148": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountBenefit' value cannot exceed the 'maxDiscountAmount' value."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38243": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'minQuantity' value is invalid. This value must be an integer."
+ },
+ "38244": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'forEachQuantity' value is invalid. This value must be an integer."
+ },
+ "38245": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'minAmount' value is invalid. For help, see the documentation for this call."
+ },
+ "38246": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'forEachAmount' value is invalid. For help, see the documentation for this call."
+ },
+ "38247": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'numberOfDiscountedItems' value is invalid. This value must be an integer."
+ },
+ "38248": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'percentOffItem' value is invalid. For help, see the documentation for this call."
+ },
+ "38249": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'percentOffOrder' value is invalid. For help, see the documentation for this call."
+ },
+ "38250": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'amountOffItem' value is invalid. For help, see the documentation for this call."
+ },
+ "38251": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'amountOffOrder' value is invalid. For help, see the documentation for this call."
+ },
+ "38266": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification.maxAmount' value."
+ },
+ "38268": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification'."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "required": false
},
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/TargetedKeywordsPagedCollection"
- }
- }
+ "/item_promotion/{promotion_id}": {
+ "get": {
+ "tags": [
+ "item_promotion"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method returns the complete details of the threshold discount specified by the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's discounts.",
+ "operationId": "getItemPromotion",
+ "parameters": [
+ {
+ "name": "promotion_id",
+ "in": "path",
+ "description": "This path parameter takes a concatenation of the ID of the discount you want to retrieve plus the marketplace ID on which the discount is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the discount (promotionId) is a unique eBay-assigned value that's generated when the discount is created. The Marketplace ID is the ENUM value of eBay marketplace where the discount is hosted.
Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.
Example: 1********5@EBAY_US",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ItemPromotionResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38203": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Resource not found. Check the ID and try the call again."
+ },
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "345076": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot get the details of a promotion that was not created through the API."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "put": {
+ "tags": [
+ "item_promotion"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method updates the specified threshold discount with the new configuration that you supply in the request. Indicate the discount you want to update using the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's discounts.
When updating a discount, supply all the fields that you used to configure the original discount (and not just the fields you are updating). eBay replaces the specified discount with the values you supply in the update request and if you don't pass a field that currently has a value, the update request will fail.
The parameters you are allowed to update with this request depend on the status of the discount you're updating:
- DRAFT or SCHEDULED discounts: You can update any of the parameters in these discounts that have not yet started to run, including the discountRules.
- RUNNING or PAUSED discounts: You can change the endDate and the item's inventory but you cannot change the discount or the start date.
- ENDED discounts: Nothing can be changed.
Tip: When updating a RUNNING or PAUSED discount, set the status field to SCHEDULED for the update request. When the discount is updated, the previous status (either RUNNING or PAUSED) is retained.
",
+ "operationId": "updateItemPromotion",
+ "parameters": [
+ {
+ "name": "promotion_id",
+ "in": "path",
+ "description": "This path parameter takes a concatenation of the ID of the discount you want to update plus the marketplace ID on which the discount is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the discount (promotionId) is a unique eBay-assigned value that's generated when the discount is created. The Marketplace ID is the ENUM value of eBay marketplace where the discouint is hosted.
Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.
Example: 1********5@EBAY_US",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the fields that describe an item discount.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the fields that describe an item discount.",
+ "$ref": "#/components/schemas/ItemPromotion"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BaseResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38226": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID must be numeric if you're using listingIds."
+ },
+ "38227": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The listing ID is invalid."
+ },
+ "38263": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}."
+ },
+ "38272": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This listing is not eligible for a promotion because it's an auction-style listing."
+ },
+ "38273": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing."
+ },
+ "38274": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "You haven't included electronic payment method as a payment method. In order to make this listing eligible, update it to include electronic payment method ."
+ },
+ "38275": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "This SKU used in inventoryReferenceId matches an item that is part of a listing with variations. This SKU is only eligible if you add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label)."
+ },
+ "345112": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid Store category. Please refer to API documentation to source allowed values."
+ },
+ "345113": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid marketplace category ID. Please refer to API documentation for the supported values."
+ },
+ "345137": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'priority' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345138": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'description' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345139": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'applyDiscountToSingleItemOnly' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345140": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'promotionImageUrl' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345142": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'applyDiscountToSingleItemOnly' is currently not supported for this Marketplace ID. For help, see the documentation for this call."
+ },
+ "345143": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'couponType' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345144": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'maxCouponRedemptionPerUser' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345145": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'maxDiscountAmount' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345146": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'budget' can not be set for this promotion type. For help, see the documentation for this call."
+ },
+ "345147": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'couponCode' can not be set for this promotion type. For help, see the documentation for this call."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38203": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Resource not found. Check the ID and try the call again."
+ },
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "38207": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion priority is invalid. Please check and try the call again."
+ },
+ "38210": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot change the priority of a promotion that is ended or deleted."
+ },
+ "38218": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A valid entry is required for {fieldName}."
+ },
+ "38219": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The start date and time must be earlier than the end date and time."
+ },
+ "38220": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The end date and time must be later than the current date and time."
+ },
+ "38225": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update a promotion that has ended."
+ },
+ "38228": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The amount value of '{fieldName}' contains decimals, only integers are supported."
+ },
+ "38229": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The start date and time should be later than the current date and time."
+ },
+ "38232": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update the promotion discount for an active promotion."
+ },
+ "38234": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "HTML is not allowed in the '{fieldName}' field."
+ },
+ "38235": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the '{fieldName}' field. For help, see the documentation for this call."
+ },
+ "38236": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountSpecification' data is missing, which is required by this call. For help, see the documentation for this call."
+ },
+ "38237": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these fields: 'minQuantity', 'forEachQuantity', 'minAmount', or 'forEachAmount' in 'discountSpecification'. For help, see the documentation for this call."
+ },
+ "38238": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountBenefit' data is missing, which is required by this call. For help, see the documentation for this call."
+ },
+ "38239": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these fields: 'percentageOffOrder', 'amountOffOrder', 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call."
+ },
+ "38240": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
+ },
+ "38241": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This discount rule combination is currently not supported. For help, see the documentation for this call."
+ },
+ "38242": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'."
+ },
+ "38253": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The data combination of 'DiscountSpecification' and 'DiscountBenefit' is not valid for this promotion type. For help, see the documentation for this call."
+ },
+ "38255": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion description exceeds the maximum length, which is {promoDescriptionLength}."
+ },
+ "38256": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion name exceeds the maximum length, which is {promoNameLength}."
+ },
+ "38257": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This promotion type supports only one discount rule for the item promotion."
+ },
+ "38260": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "To update the start date of a promotion, the promotion must be in draft or scheduled state."
+ },
+ "38261": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Promotions are currently limited to a maximum of {maxListingInclLimit} parent items, when entering item IDs or choosing from live inventory."
+ },
+ "38262": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can only include up to {maxSkuInclLimit} SKUs or custom labels in inventoryItems."
+ },
+ "38265": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Number of discount items is greater than the quantity specified in 'DiscountSpecification'."
+ },
+ "38267": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'DiscountBenefit.amountOffOrder' field cannot be used with the 'DiscountSpecification.numberOfDiscountedItems' field. This parameter is reserved for Buy x, Get x discounts. For help, see the documentation for this call."
+ },
+ "38269": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The promotion ID does not match any of the seller's promotions."
+ },
+ "38270": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The currency type does not match what is used for the Marketplace ID submitted."
+ },
+ "38271": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Only new or scheduled promotions can be saved as a draft."
+ },
+ "345077": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update a promotion that was not created through the API."
+ },
+ "345110": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only one of Inventory Items, Listing IDs or Rules in the Inventory Criterion."
+ },
+ "345111": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify Rules when using the Inventory by Value Criterion."
+ },
+ "345114": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A Category scope is required for the Rule. Please refer to API documentation for allowed values."
+ },
+ "345115": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "At least one Category is required. Please provide a valid input for this field and try again."
+ },
+ "345116": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only Marketplace categories or Store categories when creating Rules."
+ },
+ "345118": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion."
+ },
+ "345120": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid Item condition. Please refer to API documentation for allowed values."
+ },
+ "345121": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify Rules or inventory items when using the Inventory by ALL Criterion."
+ },
+ "345122": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "category ids cannot be specified with the inventory of type any."
+ },
+ "345123": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "brands cannot be specified with inventory of type any or Store."
+ },
+ "345124": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Exclusions are currently limited to a maximum of 100 parent items, when entering Inventory Items or Listing IDs, or choosing from live inventory."
+ },
+ "345125": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify a child Marketplace Category ID when the parent Marketplace Category ID is already specified. Please refer to the API documentation to source allowed values."
+ },
+ "345126": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot specify a child Store Category ID when the parent Store Category ID is already specified. Please refer to the API documentation to source allowed values."
+ },
+ "345127": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Category aspects are not supported in this version."
+ },
+ "345128": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The minimum discount rules required for volume discount promotions are {numOfDiscountRules}"
+ },
+ "345129": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountRules.ruleOrder' is missing or invalid for one of the discount rules for volume discount promotions. see the documentation for this call."
+ },
+ "345130": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can include up to a maximum of {numOfDiscountRules} discount rules in a volume discount promotion."
+ },
+ "345131": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Each 'minQuantity' value should be one greater than the 'minQuantity' value of the previous discount rule."
+ },
+ "345132": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The discount value is invalid for one of the discount rules for volume discount promotions. see the documentation for this call."
+ },
+ "345133": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Each 'percentageOffOrder' or 'amountOffOrder' value should be greater than the 'percentageOffOrder' or 'amountOffOrder' value of the previous discount rule for volume discount promotions."
+ },
+ "345134": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "This promotionType is currently not supported. For help, see the documentation for this call."
+ },
+ "345135": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update the promotion type for a promotion."
+ },
+ "345136": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountBenefit' specified is not supported for this promotion Type. For help, see the documentation for this call."
+ },
+ "345137": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'couponCode' value is invalid. For help, see the documentation for this call."
+ },
+ "345138": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update the 'couponCode' for an active or paused promotion."
+ },
+ "345139": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'couponType' data is invalid. For help, see the documentation for this call."
+ },
+ "345140": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update the 'couponType' for an active or paused promotion."
+ },
+ "345141": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxCouponRedemptionPerUser' value is invalid. For help, see the documentation for this call."
+ },
+ "345142": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update the 'maxCouponRedemptionPerUser' for an active or paused promotion."
+ },
+ "345143": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'maxDiscountAmount' value is invalid. For help, see the documentation for this call.\n"
+ },
+ "345144": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update the 'maxDiscountAmount' for an active or paused promotion."
+ },
+ "345145": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot apply a 'budget' to an active or paused promotion. For help, see the documentation for this call."
+ },
+ "345146": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'budget' value is invalid. For help, see the documentation for this call."
+ },
+ "345147": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'budget' value cannot be decreased. For help, see the documentation for this call."
+ },
+ "345148": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A coupon with this 'couponCode' already exists. Please try a different 'couponCode'."
+ },
+ "345149": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'currency' for 'maxDiscountAmount' and 'budget' has to be same. For help, see the documentation for this call."
+ },
+ "345150": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "'promotionType' CODED_COUPON is currently not supported for this Marketplace ID. For help, see the documentation for this call."
+ },
+ "345151": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'discountBenefit' value cannot exceed the 'maxDiscountAmount' value."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38243": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'minQuantity' value is invalid. This value must be an integer."
+ },
+ "38244": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'forEachQuantity' value is invalid. This value must be an integer."
+ },
+ "38245": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'minAmount' value is invalid. For help, see the documentation for this call."
+ },
+ "38246": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'forEachAmount' value is invalid. For help, see the documentation for this call."
+ },
+ "38247": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'numberOfDiscountedItems' value is invalid. This value must be an integer."
+ },
+ "38248": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'percentOffItem' value is invalid. For help, see the documentation for this call."
+ },
+ "38249": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'percentOffOrder' value is invalid. For help, see the documentation for this call."
+ },
+ "38250": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'amountOffItem' value is invalid. For help, see the documentation for this call."
+ },
+ "38251": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'amountOffOrder' value is invalid. For help, see the documentation for this call."
+ },
+ "38266": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification.maxAmount' value."
+ },
+ "38268": {
+ "domain": "API_MARKETING",
+ "category": "BUSINESS",
+ "description": "The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification'."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, please contact support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "delete": {
+ "tags": [
+ "item_promotion"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method deletes the threshold discount specified by the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's discounts.
You can delete any discount with the exception of those that are currently active (RUNNING). To end a running threshold discount, call updateItemPromotion and adjust the endDate field as appropriate.",
+ "operationId": "deleteItemPromotion",
+ "parameters": [
+ {
+ "name": "promotion_id",
+ "in": "path",
+ "description": "This path parameter takes a concatenation of the ID of the discount you want to delete plus the marketplace ID on which the discount is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the discount (promotionId) is a unique eBay-assigned value that's generated when the discount is created. The Marketplace ID is the ENUM value of eBay marketplace where the discount is hosted.
Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.
Example: 1********5@EBAY_US",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38203": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Resource not found. Check the ID and try the call again."
+ },
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "38216": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A promotion can only be deleted if it is paused or ended."
+ },
+ "345077": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update a promotion that was not created through the API."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, please contact support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35013": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing Id {listingId} is not valid."
- },
- "35041": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'marketplaceId' is required."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No ad group found for ad group id {ad_group_id}."
- },
- "36301": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The provided keyword match type is not supported. Valid values are: {matchTypeValues}."
- },
- "70006": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The provided exclusion is not supported. Valid values are {supportedExclusions}."
- },
- "70007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The provided additionalInfo is not supported. Valid values are {supportedAdditionalInfo}."
- }
- }
+ },
+ "/promotion/{promotion_id}/get_listing_set": {
+ "get": {
+ "tags": [
+ "promotion"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method returns the set of listings associated with the promotion_id specified in the path parameter. Call getPromotions to retrieve the IDs of a seller's discounts. The listing details are returned in a paginated set and you can control and results returned using the following query parameters: limit, offset, q, sort, and status.
- Maximum associated listings returned: 200
- Default number of listings returned: 200
",
+ "operationId": "getListingSet",
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "Specifies the maximum number of discounts returned on a page from the result set.
Default: 200
Maximum: 200",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "Specifies the number of discounts to skip in the result set before returning the first discount in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "promotion_id",
+ "in": "path",
+ "description": "This path parameter takes a concatenation of the ID of the discount associated with the listing set plus the marketplace ID on which the discount is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the discount (promotionId) is a unique eBay-assigned value that's generated when the discount is created. The Marketplace ID is the ENUM value of eBay marketplace where the discount is hosted.
Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.
Example: 1********5@EBAY_US",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "q",
+ "in": "query",
+ "description": "Reserved for future use.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sort",
+ "in": "query",
+ "description": "Specifies the order in which to sort the associated listings in the response. If you precede the supplied value with a dash, the response is sorted in reverse order.
Example:
sort=PRICE - Sorts the associated listings by their current price in ascending order
sort=-TITLE - Sorts the associated listings by their title in descending alphabetical order (Z-Az-a)
Valid values: For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/marketing/types/csb:SortField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "status",
+ "in": "query",
+ "description": "This query parameter applies only to markdown discounts. It filters the response based on the indicated status of the discount.
Note: Currently, the only supported value for this parameter is MARKED_DOWN, which indicates active markdown discounts. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/marketing/types/sme:ItemMarkdownStatusEnum",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ItemsPagedCollection"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "345062": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Sort is not supported for this promotion type. For help, see the documentation for this call."
+ },
+ "345068": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The value of the 'Status' parameter is invalid. For help, see the documentation for this call."
+ },
+ "345069": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The 'Status' parameter is only supported for itemPriceMarkdownPromotions. For help, see the documentation for this call."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38203": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Resource not found. Check the ID and try the call again."
+ },
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "38211": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The offset value must be an integer value greater than or equal to zero."
+ },
+ "38212": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The sort value was not valid. For the valid values, see the documentation for this call."
+ },
+ "38213": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can query a limit of between 0 and 200 promotion records at a time. Update the request and resubmit the call."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35051": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}."
- },
- "35054": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing Id {listingId} was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace."
- },
- "35057": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing Id {listingId} does not belong to the seller making this call."
- },
- "35068": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of listing Ids. Only {maxSupportedNumber} listings are supported per call."
- }
- }
+ },
+ "/promotion": {
+ "get": {
+ "tags": [
+ "promotion"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method returns a list of a seller's undeleted discounts. The call returns up to 200 currently-available discounts on the specified marketplace. While the response body does not include the discount's discountRules or inventoryCriterion containers, it does include the promotionHref (which you can use to retrieve the complete details of the discount).
Use query parameters to sort and filter the results by the number of discounts to return, the discount state or type, and the eBay marketplace. You can also supply keywords to limit the response to the discounts that contain that keywords in the title of the discount.
Maximum returned: 200
",
+ "operationId": "getPromotions",
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "Specifies the maximum number of discounts returned on a page from the result set.
Default: 200
Maximum: 200",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "query",
+ "description": "This parameter specifies eBay marketplace ID of the site where the discount is hosted.
See MarketplaceIdEnum for supported Marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "Specifies the number of discounts to skip in the result set before returning the first discount in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "promotion_status",
+ "in": "query",
+ "description": "This parameter specifies the discount state by which you want to filter the results. The response contains only those discounts that match the state you specify.
See PromotionStatusEnum for supported values.
Maximum number of input values: 1",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "promotion_type",
+ "in": "query",
+ "description": "This parameter specifies the campaign discounts type by which you want to filter the results.
See PromotionTypeEnum for supported values.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "q",
+ "in": "query",
+ "description": "A string consisting of one or more keywords. eBay filters the response by returning only the discounts that contain the supplied keywords in the title.
Example: \"iPhone\" or \"Harry Potter.\"
Commas that separate keywords are ignored. For example, a keyword string of \"iPhone, iPad\" equals \"iPhone iPad\", and each results in a response that contains discounts with both \"iPhone\" and \"iPad\" in the title.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sort",
+ "in": "query",
+ "description": "Specifies the order for how to sort the response. If you precede the supplied value with a dash, the response is sorted in reverse order.
Example:
sort=END_DATE Sorts the discounts in the response by their end dates in ascending order
sort=-PROMOTION_NAME Sorts the discounts by their name in descending alphabetical order (Z-Az-a)
Valid values:START_DATEEND_DATEPROMOTION_NAME
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/marketing/types/csb:SortField",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PromotionsPagedCollection"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "38211": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The offset value must be an integer value greater than or equal to zero."
+ },
+ "38212": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The sort value was not valid. For the valid values, see the documentation for this call."
+ },
+ "38213": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can query a limit of between 0 and 200 promotion records at a time. Update the request and resubmit the call."
+ },
+ "38240": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
+ },
+ "345141": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the 'promotionType' field. For help, see the documentation for this call."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
+ },
+ "/promotion/{promotion_id}/pause": {
+ "post": {
+ "tags": [
+ "promotion"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method pauses a currently-active (RUNNING) threshold discount and changes the state of the discount from RUNNING to PAUSED. Pausing a discount makes the discount temporarily unavailable to buyers and any currently-incomplete transactions will not receive the offer until the discount is resumed. Also, discount teasers are not displayed when a discount is paused.
Pass the ID of the discount you want to pause using the promotion_id path parameter. Call getPromotions to retrieve the IDs of the seller's discounts.
Note: You can only pause threshold discounts (you cannot pause markdown discounts).",
+ "operationId": "pausePromotion",
+ "parameters": [
+ {
+ "name": "promotion_id",
+ "in": "path",
+ "description": "This path parameter takes a concatenation of the ID of the active discount being paused plus the marketplace ID on which the discount is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the discount (promotionId) is a unique eBay-assigned value that's generated when the discount is created. The Marketplace ID is the ENUM value of eBay marketplace where the discount is hosted.
Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.
Example: 1********5@EBAY_US",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38203": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Resource not found. Check the ID and try the call again."
+ },
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "38214": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "A promotion can only be paused if it is scheduled or running."
+ },
+ "345077": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update a promotion that was not created through the API."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/clone": {
- "post": {
- "tags": [
- "campaign"
- ],
- "description": "This method clones (makes a copy of) the specified campaign's campaign criterion. The campaign criterion is a container for the fields that define the criteria for a rule-based campaign.To clone a campaign, supply the campaign_id as a path parameter in your call. There is no request payload.
The ID of the newly-cloned campaign is returned in the Location response header.
Call getCampaigns to retrieve a seller's current campaign IDs.
Requirement: In order to clone a campaign, the campaignStatus must be ENDED and the campaign must define a set of selection rules (it must be a rules-based campaign).
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
- "operationId": "cloneCampaign",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created. This ID is the campaign ID of the campaign being cloned.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
+ "/promotion/{promotion_id}/resume": {
+ "post": {
+ "tags": [
+ "promotion"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method restarts a threshold discount that was previously paused and changes the state of the discount from PAUSED to RUNNING. Only discounts that have been previously paused can be resumed. Resuming a discount reinstates the teasers and any transactions that were in motion before the discount was paused will again be eligible for the discount.
Pass the ID of the discount you want to resume using the promotion_id path parameter. Call getPromotions to retrieve the IDs of the seller's discounts.",
+ "operationId": "resumePromotion",
+ "parameters": [
+ {
+ "name": "promotion_id",
+ "in": "path",
+ "description": "This path parameter takes a concatenation of the ID of the paused discount being resumed with the listing set plus the marketplace ID on which the discount is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the discount (promotionId) is a unique eBay-assigned value that's generated when the discount is created. The Marketplace ID is the ENUM value of eBay marketplace where the discount is hosted.
Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.
Example: 1********5@EBAY_US",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38203": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Resource not found. Check the ID and try the call again."
+ },
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "38209": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot resume a promotion that is not paused or has already ended."
+ },
+ "345077": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You cannot update a promotion that was not created through the API."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
+ },
+ "/promotion_report": {
+ "get": {
+ "tags": [
+ "promotion_report"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method generates a report that lists the seller's running, paused, and ended discounts for the specified eBay marketplace. The result set can be filtered by the discount status and the number of results to return. You can also supply keywords to limit the report to discounts that contain the specified keywords.
Specify the eBay marketplace for which you want the report run using the marketplace_id query parameter. Supply additional query parameters to control the report as needed.",
+ "operationId": "getPromotionReports",
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "Specifies the maximum number of discounts returned on a page from the result set.
Default: 200
Maximum: 200",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "query",
+ "description": "This parameter specifies the eBay marketplace ID of the site for which you want the discounts report.
See MarketplaceIdEnum for supported Marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "Specifies the number of discounts to skip in the result set before returning the first discount in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "promotion_status",
+ "in": "query",
+ "description": "This parameter specifies the discount state by which you want to filter the results.
See PromotionStatusEnum for supported values.
Maximum number of input values: 1",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "promotion_type",
+ "in": "query",
+ "description": "This parameter specifies the campaign discount type by which you want to filter the results.
See PromotionTypeEnum for supported values.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "q",
+ "in": "query",
+ "description": "A string consisting of one or more keywords. eBay filters the response by returning only the discounts that contain the supplied keywords in the discount title.
Example: \"iPhone\" or \"Harry Potter.\"
Commas that separate keywords are ignored. For example, a keyword string of \"iPhone, iPad\" equals \"iPhone iPad\", and each results in a response that contains discounts with both \"iPhone\" and \"iPad\" in the title.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PromotionsReportPagedCollection"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ },
+ "38211": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The offset value must be an integer value greater than or equal to zero."
+ },
+ "38213": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "You can query a limit of between 0 and 200 promotion records at a time. Update the request and resubmit the call."
+ },
+ "38240": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
+ },
+ "345141": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "Invalid input for the 'promotionType' field. For help, see the documentation for this call."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
- ],
- "requestBody": {
- "description": "This type defines the fields for a clone campaign request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the fields for a clone campaign request.",
- "$ref": "#/components/schemas/CloneCampaignRequest"
- }
+ },
+ "/promotion_summary_report": {
+ "get": {
+ "tags": [
+ "promotion_summary_report"
+ ],
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This method generates a report that summarizes the seller's discounts for the specified eBay marketplace. The report returns information on RUNNING, PAUSED, and ENDED discounts (deleted reports are not returned) and summarizes the seller's campaign performance for all discounts on a given site.
For information about summary reports, see Reading the item discount Summary report.",
+ "operationId": "getPromotionSummaryReport",
+ "parameters": [
+ {
+ "name": "marketplace_id",
+ "in": "query",
+ "description": "This parameter specifies the eBay marketplace ID of the site for which you want a discount summary report.
See MarketplaceIdEnum for supported Marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SummaryReportResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38204": {
+ "domain": "API_MARKETING",
+ "category": "REQUEST",
+ "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "38201": {
+ "domain": "API_MARKETING",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- "required": true
},
- "responses": {
- "201": {
- "description": "Success",
- "headers": {
- "Location": {
- "schema": {
- "type": "string",
- "description": "The location response header contains the getCampaign URI to the retrieve the newly created campaign."
- }
- }
+ "/email_campaign": {
+ "get": {
+ "tags": [
+ "email_campaign"
+ ],
+ "description": "This method retrieves a list of email campaigns from a seller's eBay store.
Users can filter the results by email campaign type, email campaign status, and marketplace ID using the q query parameter.",
+ "operationId": "getEmailCampaigns",
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The maximum number of email campaigns returned in a page.
Min value: 1
Max value: 200",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "The number of results to skip in a pagination query. This value cannot be less than zero.
Default value: 0",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "q",
+ "in": "query",
+ "description": "This field contains filter criteria for the results returned. Filter by email campaign type, email campaign status, and marketplace ID.
For example, setting q=campaignType:WELCOME,ITEM_SHOWCASE will return only Welcome and Item Showcase email campaigns.
Note: At least one campaignType value must be set through the q query parameter. If no other filters are set, all email campaigns for the specified campaign type(s) will be returned in the results set.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "sort",
+ "in": "query",
+ "description": "The criteria for sorting email campaign results. See ItemSortEnum for sorting options and their enum values.
Default: NEWLY_LISTED",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetEmailCampaignsResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "STORE_CRM",
+ "category": "BUSINESS",
+ "description": "A store subscription is required for this call, please check the store subscription status for current seller."
+ },
+ "35301": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The paginated query limit {limit} value is missing or invalid. The value cannot be less than or equal to zero and also cannot be greater than maximum value."
+ },
+ "35302": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The paginated query offset {offset} value is missing or invalid. The value cannot be less zero and also cannot be greater than maximum value."
+ },
+ "35303": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The query string {q} is malformed. For the valid format, see the documentation for this call."
+ },
+ "35304": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The email campaign type {campaignType} in query string {q} is not supported. For the valid values, see the documentation for this call."
+ },
+ "35305": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The 'marketplaceId' in query string {q} is not supported. For the valid values, see the documentation for this call."
+ },
+ "35306": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The email campaign status {status} in query string {q} is not supported. For the valid values, see the documentation for this call."
+ },
+ "35307": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The campaign type {campaignType} in query string {q} is required."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35000": {
+ "domain": "STORE_CRM",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
},
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35006": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'fundingStrategy' is required for this call."
- },
- "35007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
- },
- "35019": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Campaign name is required for this call."
- },
- "35020": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
- },
- "35021": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign with the name of {campaignName} already exists. Please provide a different name."
- },
- "35023": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
- },
- "35024": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign start date {startDate} cannot be after the end date {endDate}."
- },
- "35025": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign start date is required."
- },
- "35026": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign start or end date {date} cannot be in the past."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36101": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This functionality is not supported for the CPC funding model."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35062": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} has not ended yet. cloneCampaign is supported only for criterion based campaigns that have ended."
- },
- "35065": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This operation is only supported for criterion based campaigns."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "35106": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'BidPercentage' should be provided when selected 'adRateStrategy' is 'FIXED'."
- },
- "35107": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'dynamicAdRatePreferences' can be provided only when selected 'adRateStrategy' is 'DYNAMIC'."
- },
- "35108": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'adRateAdjustmentPercent' {adRateAdjustmentPercent} is not valid. Please set 'adRateAdjustmentPercent' {adRateAdjustmentPercent} between {minAllowedAdRateAdjustmentPercent}% - {maxAllowedAdRateAdjustmentPercent}%."
- },
- "35109": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'adRateCapPercent' {adRateCapPercent} is not valid. Please set 'adRateCapPercent' between {minAllowedAdRateCapPercent}% - {maxAllowedAdRateCapPercent}%."
- },
- "35110": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'adRateStrategy' is not supported for CPC funding model."
- },
- "35111": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'dynamicAdRatePreferences' is not supported for CPC funding model."
- },
- "35112": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'adRateStrategy' is currently only supported for criterion based campaign with 'autoselectFutureInventory' as True."
- },
- "35113": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'dynamicAdRatePreferences' is currently only supported for criterion based campaign with 'autoselectFutureInventory' as True."
- },
- "35114": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'dynamicAdRatePreferences' list currently can only support one element containing dynamicAdRatePreference. Please remove additional elements and try again."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
+ "post": {
+ "tags": [
+ "email_campaign"
+ ],
+ "description": "This method creates a new email campaign. An eBay store owner can create six different types of email campaigns: Welcome, New products & collections, Coupon, Sale event + markdown, Order discount, and Volume pricing.
A successful createEmailCampaign request returns the emailCampaignId assigned to the new email campaign.
The fields emailCampaignType, audienceCodes, itemSelectMode, subject, and personalizedMessage are required for all email campaign types.
Specific email campaign types have required values for additional fields. For more information on the email campaign types, see the Store Email Campaigns section of the Selling Integration Guide. ",
+ "operationId": "createEmailCampaign",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "The eBay marketplace that the email campaign interfaces with.
eBay marketplaces correspond to geographical regions or large submarkets of regions. For example, EBAY-US corresponds to the United States market.
See MarketplaceIdEnum for supported values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "Create a new email campaign request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Create a new email campaign request.",
+ "$ref": "#/components/schemas/CreateEmailCampaignRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateEmailCampaignResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "STORE_CRM",
+ "category": "BUSINESS",
+ "description": "A store subscription is required for this call, please check the store subscription status for current seller."
+ },
+ "35201": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'marketplaceId' value is not supported. For the valid values, see the documentation for this call."
+ },
+ "35202": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'emailCampaignType' value is not supported. For the valid values, see the documentation for this call."
+ },
+ "35203": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'audiences' is required for this call."
+ },
+ "35204": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'subject' is required for this call."
+ },
+ "35205": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'personalizedMessage' is required for this call."
+ },
+ "35206": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'subject' length is too long. For maximum limits, see the documentation for this call."
+ },
+ "35207": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'audiences' value is not suitable for current email campaign type."
+ },
+ "35208": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'itemIds' is required for this call."
+ },
+ "35209": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "For 'WELCOME' type campaign, 'itemIds' should be empty."
+ },
+ "35210": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The item {itemIds} size exceeds maximum. For maximum limits, see the documentation for this call."
+ },
+ "35211": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "No eligible items for current campaign."
+ },
+ "35212": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'promotionId' is required for this call."
+ },
+ "35213": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'promotionId' is invalid, promotion may be inactive or non-exist."
+ },
+ "35214": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'scheduleDate' is not required for this call."
+ },
+ "35215": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'scheduleDate' is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm.sssZ) string."
+ },
+ "35216": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "Only one 'WELCOME' type email campaign is allowed for one marketplace."
+ },
+ "35217": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "Only one automated promotion email campaign is allowed for one campaign type per marketplace id."
+ },
+ "35218": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'personalizedMessage' length is too long. For maximum limits, see the documentation for this call."
+ },
+ "35219": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The email campaign schedule date {scheduleDate} must be in the future."
+ },
+ "35220": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'itemIds' contains ineligible item id, please check the item list"
+ },
+ "35221": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'itemSelectMode' is invalid for this campaign, please see the documentation for this call."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35000": {
+ "domain": "STORE_CRM",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign": {
- "get": {
- "tags": [
- "campaign"
- ],
- "description": "This method retrieves the details for all of the seller's defined campaigns. Request parameters can be used to retrieve a specific campaign, such as the campaign's name, the start and end date, the status, and the funding model (Cost Per Sale (CPS) or Cost Per Click (CPC). You can filter the result set by a campaign name, end date range, start date range, or campaign status. You can also paginate the records returned from the result set using the limit query parameter, and control which records to return using the offset parameter.
",
- "operationId": "getCampaigns",
- "parameters": [
- {
- "name": "campaign_name",
- "in": "query",
- "description": "Specifies the campaign name. The results are filtered to include only the campaign by the specified name.
Note: The results might be null if other filters exclude the campaign with this name.
Maximum: 1 campaign name",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "campaign_status",
- "in": "query",
- "description": "Include this filter and input a specific campaign status to retrieve campaigns currently in that state.
Note: The results might not include all the campaigns with this status if other filters exclude them.
Valid values: See CampaignStatusEnum
Maximum: 1 status",
- "required": false,
- "schema": {
- "type": "string"
+ "/email_campaign/{email_campaign_id}": {
+ "get": {
+ "tags": [
+ "email_campaign"
+ ],
+ "description": "This method returns the details of a single email campaign specified by the email_campaign_id path parameter.
Call getEmailCampaigns to retrieve a list of all email campaigns from a seller's eBay store.",
+ "operationId": "getEmailCampaign",
+ "parameters": [
+ {
+ "name": "email_campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the email campaign being retrieved.
Use the getEmailCampaigns method to retrieve a list of email campaign IDs for a seller.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetEmailCampaignResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "STORE_CRM",
+ "category": "BUSINESS",
+ "description": "A store subscription is required for this call, please check the store subscription status for current seller."
+ },
+ "35501": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "No email campaign found for email campaign ID {email_campaign_id}."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35000": {
+ "domain": "STORE_CRM",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "put": {
+ "tags": [
+ "email_campaign"
+ ],
+ "description": "This method lets users update an existing email campaign. Pass the emailCampaignId in the request URL and specify the changes to field values in the request payload.
Note: You can only update the custom fields of an email campaign. Fixed values, such as the emailCampaignType, cannot be changed. For full specifications of fixed values for each email campaign type, see the createEmailCampaign method documentation.",
+ "operationId": "updateEmailCampaign",
+ "parameters": [
+ {
+ "name": "email_campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay assigned identifier for the email campaign being updated.
Use the getEmailCampaigns method to retrieve a list of email campaign IDs for a seller.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "update email campaign request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "update email campaign request",
+ "$ref": "#/components/schemas/UpdateCampaignRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UpdateEmailCampaignResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "STORE_CRM",
+ "category": "BUSINESS",
+ "description": "A store subscription is required for this call, please check the store subscription status for current seller."
+ },
+ "35801": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'audiences' is required for this call."
+ },
+ "35802": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "No email campaign found for email campaign ID {email_campaign_id}."
+ },
+ "35803": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'subject' is required for this call."
+ },
+ "35804": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'personalizedMessage' is required for this call."
+ },
+ "35805": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'subject' length is too long. For maximum limits, see the documentation for this call."
+ },
+ "35806": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'audiences' value is not suitable for current email campaign type."
+ },
+ "35807": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'itemIds' is required for this call."
+ },
+ "35808": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "For 'WELCOME' type campaign, 'itemIds' should be empty."
+ },
+ "35809": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The item {itemIds} size exceeds maximum. For maximum limits, see the documentation for this call."
+ },
+ "35810": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "No eligible items for current campaign."
+ },
+ "35811": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'promotionId' is required for this call."
+ },
+ "35812": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'promotionId' is invalid, promotion may be inactive or non-exist."
+ },
+ "35813": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'scheduleDate' is not required for this call."
+ },
+ "35814": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'scheduleDate' is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm:sssZ) string."
+ },
+ "35815": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'email_campaign_id' is not eligible for editing."
+ },
+ "35816": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'personalizedMessage' length is too long. For maximum limits, see the documentation for this call."
+ },
+ "35817": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The email campaign schedule date {scheduleDate} must be in the future."
+ },
+ "35818": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'itemIds' contains ineligible item id, please check the item list"
+ },
+ "35819": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'itemSelectMode' is invalid for this campaign, please see the documentation for this call."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35000": {
+ "domain": "STORE_CRM",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
+ },
+ "delete": {
+ "tags": [
+ "email_campaign"
+ ],
+ "description": "This method deletes the email campaign specified by the email_campaign_id path parameter.
Call getEmailCampaigns to retrieve all of the seller's email campaigns. Use the email_campaign_id of the desired email campaign in the response as the path parameter for this request.",
+ "operationId": "deleteEmailCampaign",
+ "parameters": [
+ {
+ "name": "email_campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay-assigned identifier for the email campaign being deleted.
You can retrieve the email campaign IDs for a specified seller using the getEmailCampaigns method.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeleteEmailCampaignResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "STORE_CRM",
+ "category": "BUSINESS",
+ "description": "A store subscription is required for this call, please check the store subscription status for current seller."
+ },
+ "35401": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "No email campaign found for email campaign ID {email_campaign_id}."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35000": {
+ "domain": "STORE_CRM",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "end_date_range",
- "in": "query",
- "description": "Specifies the range of a campaign's end date. The results are filtered to include only campaigns with an end date that is within specified range.
Valid format (UTC): yyyy-MM-ddThh:mm:ssZ..yyyy-MM-ddThh:mm:ssZ (campaign ends within this range)yyyy-MM-ddThh:mm:ssZ.. (campaign ends on or after this date)..yyyy-MM-ddThh:mm:ssZ (campaign ends on or before this date)2016-09-08T00:00.00.000Z..2016-09-09T00:00:00Z (campaign ends on September 08, 2016)
Note: The results might not include all the campaigns ending on this date if other filters exclude them.",
- "required": false,
- "schema": {
- "type": "string"
+ },
+ "/email_campaign/audience": {
+ "get": {
+ "tags": [
+ "email_campaign"
+ ],
+ "description": "This method retrieves all available email newsletter audiences for the email campaign type specified by the emailCampaignType path parameter.
Use the optional limit and offset path parameters to paginate the results and to control which records are returned, respectively.",
+ "operationId": "getAudiences",
+ "parameters": [
+ {
+ "name": "emailCampaignType",
+ "in": "query",
+ "description": "The email campaign type to search against.
See CampaignTypeEnum for the full list of available email campaign types and associated enum values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The maximum number of audience groups returned per page in the results set.
Min value: 1
Max value: 200
Default value: 100",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "The number of results to skip in a pagination query. This value cannot be less than 0.
Default value: 0",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetEmailCampaignAudiencesResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "STORE_CRM",
+ "category": "BUSINESS",
+ "description": "A store subscription is required for this call, please check the store subscription status for current seller."
+ },
+ "35101": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The paginated query limit {limit} value is missing or invalid. The value cannot be less than or equal to zero."
+ },
+ "35102": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The paginated query offset {offset} value is mossing or invalid. The value cannot be less than zero."
+ },
+ "35103": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The email campaign type {emailCampaignType} is not supported. For the valid value, please see the documentation for this call."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35000": {
+ "domain": "STORE_CRM",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "funding_strategy",
- "in": "query",
- "description": "Specifies the funding strategy for the campaign.
The results will be filtered to only include campaigns with the specified funding model. If not specified, all campaigns matching the other filter parameters will be returned. The results might not include these campaigns if other search conditions exclude them.
Valid Values:COST_PER_SALECOST_PER_CLICK
",
- "required": false,
- "schema": {
- "type": "string"
+ },
+ "/email_campaign/{email_campaign_id}/email_preview": {
+ "get": {
+ "tags": [
+ "email_campaign"
+ ],
+ "description": "This method returns a preview of the email sent by the email campaign indicated by the email_campaign_id path parameter.
Call getEmailCampaigns to obtain a list of email campaigns. Use the emailCampaignId value of the desired email campaign as the email_campaign_id path parameter value.
If this call is executed successfully, the response returns a content field that contains the raw HTML code of the email campaign that can then be rendered anywhere.
Note: The eBay listings in the email are sorted according to the email campaign sort criteria. The individual listings can change over time, as well.
The result of the email preview call can be treated as a snapshot of the email campaign taken at the date and time of the renderDate value found in the results of the call.",
+ "operationId": "getEmailPreview",
+ "parameters": [
+ {
+ "name": "email_campaign_id",
+ "in": "path",
+ "description": "This path parameter specifies the unique eBay assigned identifier for the email campaign associated with the preview being retrieved.
Use the getEmailCampaigns method to retrieve a list of email campaign IDs for a seller.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetEmailPreviewResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "STORE_CRM",
+ "category": "BUSINESS",
+ "description": "A store subscription is required for this call, please check the store subscription status for current seller."
+ },
+ "35601": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "No email campaign found for email campaign ID {email_campaign_id}."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35000": {
+ "domain": "STORE_CRM",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "limit",
- "in": "query",
- "description": "Specifies the maximum number of campaigns to return on a page in the paginated response.
Default: 10
Maximum: 500",
- "required": false,
- "schema": {
- "type": "string"
+ },
+ "/email_campaign/report": {
+ "get": {
+ "tags": [
+ "email_campaign"
+ ],
+ "description": "This method returns the seller's email campaign performance report for a time period specified by the startDate and endDate path parameters. The maximum date range for a report retrieved by this method is one year.
Note: The startDate and endDate must be given in UTC format, as shown in the following example:
sell/marketing/v1/email_campaign/report?startDate=2022-11-01T19:09:02.768Z&endDate=2022-12-28T19:09:02.768Z
The email report returns a list of metrics, such as the number of times an email report has been opened and resulted in clicks.",
+ "operationId": "getEmailReport",
+ "parameters": [
+ {
+ "name": "endDate",
+ "in": "query",
+ "description": "The end date for the report, given in UTC format. The maximum date range for a report retrieved by this method is one year.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "startDate",
+ "in": "query",
+ "description": "The start date for the report, given in UTC format. The maximum date range for a report retrieved by this method is one year.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetEmailReportResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35001": {
+ "domain": "STORE_CRM",
+ "category": "BUSINESS",
+ "description": "A store subscription is required for this call, please check the store subscription status for current seller."
+ },
+ "35701": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'startDate' value is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm:sssZ) string."
+ },
+ "35702": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'endDate' value is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm:sssZ) string."
+ },
+ "35703": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The query start date {startDate} cannot be later than query end date {endDate}."
+ },
+ "35704": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "The time interval between start date and end date exceeds maximum limit. For maximum limits, please see the documentation for this call."
+ },
+ "35705": {
+ "domain": "STORE_CRM",
+ "category": "REQUEST",
+ "description": "'currency' value is not supported. For the valid values, see the documentation for this call."
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "35000": {
+ "domain": "STORE_CRM",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.marketing"
+ ]
+ }
+ ]
}
- },
- {
- "name": "offset",
- "in": "query",
- "description": "Specifies the number of campaigns to skip in the result set before returning the first report in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "start_date_range",
- "in": "query",
- "description": "Specifies the range of a campaign's start date in which to filter the results. The results are filtered to include only campaigns with a start date that is equal to this date or is within specified range.
Valid format (UTC): yyyy-MM-ddThh:mm:ssZ..yyyy-MM-ddThh:mm:ssZ (starts within this range)yyyy-MM-ddThh:mm:ssZ (campaign starts on or after this date)..yyyy-MM-ddThh:mm:ssZ (campaign starts on or before this date)2016-09-08T00:00.00.000Z..2016-09-09T00:00:00Z (campaign starts on September 08, 2016)
Note: The results might not include all the campaigns with this start date if other filters exclude them.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/CampaignPagedCollectionResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35020": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
- },
- "35023": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
- },
- "35027": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The date range {dateRange} is not valid. Ensure the beginning of the range is before the end of the range."
- },
- "35028": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The format of the date range {dateRange} is invalid. The format for a date range is yyyy-MM-ddThh:mm:ss.sssZ..yyyy-MM-ddThh:mm:ss.sssZ or yyyy-MM-ddThh:mm:ss.sssZ.. or ..yyyy-MM-ddThh:mm:ss.sssZ."
- },
- "35029": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
- },
- "35030": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'offset' cannot be less than zero."
- },
- "35043": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign status of {campaignStatus} is either invalid or not supported for this operation."
- },
- "35079": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Funding strategy needs to be one of {fundingStrategy} types."
- }
- }
- }
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "post": {
- "tags": [
- "campaign"
- ],
- "description": "This method creates a Promoted Listings ad campaign. A Promoted Listings campaign is the structure into which you place the ads or ad group for the listings you want to promote.
Identify the items you want to place into a campaign either by \"key\" or by \"rule\" as follows:
- Rules-based campaigns – A rules-based campaign adds items to the campaign according to the criteria you specify in your call to createCampaign. You can set the autoSelectFutureInventory request field to
true so that after your campaign launches, eBay will regularly assess your new, revised, or newly-eligible listings to determine whether any should be added or removed from your campaign according to the rules you set. If there are, eBay will add or remove them automatically on a daily basis. - Key-based campaigns – Add items to an existing campaign using either listing ID values or Inventory Reference values:
- Add listingId values to an existing campaign by calling either createAdByListingID or bulkCreateAdsByListingId.
- Add inventoryReference values to an existing campaign by calling either createAdByInventoryReference or bulkCreateAdsByInventoryReference.
- Add an ad group to an existing campaign by calling createAdGroup.
Note: No matter how you add items to a Promoted Listings campaign, each campaign can contain ads for a maximum of 50,000 items.
If a rules-based campaign identifies more than 50,000 items, ads are created for only the first 50,000 items identified by the specified criteria, and ads are not created for the remaining items.
Creating a campaign
To create a basic campaign, supply:
- The user-defined campaign name
- The start date (and optionally the end date) of the campaign
- The eBay marketplace on which the campaign is hosted
- Details on the campaign funding model
The campaign funding model specifies how the Promoted Listings fee is calculated. Currently, the supported funding models are COST_PER_SALE and COST_PER_CLICK. For complete information on how the fee is calculated and when it applies, see Promoted Listings fees.
If you populate the campaignCriterion object in your createCampaign request, campaign \"ads\" are created by \"rule\" for the listings that meet the criteria you specify, and these ads are associated with the newly created campaign.
For details on creating Promoted Listings campaigns and how to select the items to be included in your campaigns, see Promoted Listings campaign creation.
For recommendations on which listings are prime for a Promoted Listings ad campaign and to get guidance on how to set the bidPercentage field, see Using the Recommendation API to help configure campaigns.
Tip: See Promoted Listings requirements and restrictions for the details on the marketplaces that support Promoted Listings via the API. See Promoted Listings restrictions for details about campaign limitations and restrictions.
",
- "operationId": "createCampaign",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This type defines the fields for the create campaign request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the fields for the create campaign request.",
- "$ref": "#/components/schemas/CreateCampaignRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "201": {
- "description": "Created",
- "headers": {
- "Location": {
- "schema": {
- "type": "string",
- "description": "The location response header contains the getCampaign URI to the newly created campaign. The URL includes the eBay-assigned campaignId, which you can use to reference the campaign."
- }
- }
- },
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "35103": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This campaign has reached maximum capacity of {maxSupportedNumber} listings. To continue promoting listings, create a new campaign."
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35003": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'campaignCriterion' is required for a criterion based campaign."
- },
- "35004": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "One of the selectionRule containers is empty. You must specify at least one rule in each selectionRule container. Note: 'categoryScope' is not a rule."
- },
- "35005": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'selectionRules' is required for criterion based campaigns."
- },
- "35006": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'fundingStrategy' is required for this call."
- },
- "35007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
- },
- "35008": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The category ID {categoryId} is not valid."
- },
- "35009": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing Condition ID {listingConditionId} is not valid. Refer to the API call documentation for a list of valid values."
- },
- "35015": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'maxPrice' or 'minPrice' value is missing or invalid. The value cannot be less than or equal to zero."
- },
- "35016": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'minPrice' {minPrice} cannot be greater than the 'maxPrice' {maxPrice}."
- },
- "35017": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'currency' is not valid or missing."
- },
- "35019": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Campaign name is required for this call."
- },
- "35020": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
- },
- "35021": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign with the name of {campaignName} already exists. Please provide a different name."
- },
- "35022": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The brand name {brandName} is not valid."
- },
- "35023": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
- },
- "35024": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign start date {startDate} cannot be after the end date {endDate}."
- },
- "35025": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign start date is required."
- },
- "35026": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign start or end date {date} cannot be in the past."
- },
- "35038": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The funding model is required. Valid values for 'fundingModel' are: {fundingModelValues}."
- },
- "35039": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'categoryScope' is required for criterion based campaigns using category based listing selection rules. Valid values are: {categoryScopeValues}"
- },
- "35041": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'marketplaceId' is required."
- },
- "35042": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The criterion type is required for criterion based campaigns. Valid values are: {criterionTypeValues}."
- },
- "36101": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The daily budget value format is a maximum of two decimal points."
- }
- }
- }
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35051": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}."
- },
- "35052": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
- },
- "35053": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "MarketplaceId: {marketplaceId} and Currency: {currency} for the listing selection rule do not match."
- },
- "35067": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The seller must accept the Promoted Listing terms and conditions. For the requirements to use the Promoted Listing API, refer to the documentation."
- },
- "35069": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "No more than {maxNumberOfSelectionRules} listing selection rules are allowed in a campaign."
- },
- "35072": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The number of listings that result from the rules exceeds the maximum number of listings allowed in a campaign, which is {maxSupportedNumber}. Refine the rules and submit the call again."
- },
- "35074": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "There were no eligible listings found for the selection rules provided. Please check the rules and submit the call again."
- },
- "35075": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "35104": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'categoryScope' STORE can not be found. Please define the store categories first or use 'categoryScope' MARKETPLACE to select categories."
- },
- "35106": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'BidPercentage' should be provided when selected 'adRateStrategy' is 'FIXED'."
- },
- "35107": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'dynamicAdRatePreferences' can be provided only when selected 'adRateStrategy' is 'DYNAMIC'."
- },
- "35108": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'adRateAdjustmentPercent' {adRateAdjustmentPercent} is not valid. Please set 'adRateAdjustmentPercent' {adRateAdjustmentPercent} between {minAllowedAdRateAdjustmentPercent}% - {maxAllowedAdRateAdjustmentPercent}%."
- },
- "35109": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'adRateCapPercent' {adRateCapPercent} is not valid. Please set 'adRateCapPercent' between {minAllowedAdRateCapPercent}% - {maxAllowedAdRateCapPercent}%."
- },
- "35110": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'adRateStrategy' is not supported for CPC funding model."
- },
- "35111": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'dynamicAdRatePreferences' is not supported for CPC funding model."
- },
- "35114": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'dynamicAdRatePreferences' list currently can only support one element containing dynamicAdRatePreference. Please remove additional elements and try again."
- },
- "36151": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'campaignCriterion' {campaignCriterion} is not supported for CPC funding model."
- },
- "36152": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'bidPercentage' is not supported for CPC funding model."
- },
- "36153": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget currency {currency} is not supported for {fieldName}. The supported currency for the {marketplaceId} marketplace is {supportedCurrencyCode}."
- },
- "36154": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget below minimum allowed {minAllowed}."
- },
- "36155": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget above maximum allowed {maxAllowed}."
- },
- "36156": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "campaignBudget is not supported for CPS funding model."
- },
- "36157": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget is required for campaigns with CPC funding model."
- },
- "36158": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget value format {dailyBudgetValue} cannot have more than 2 decimal places."
- },
- "36159": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'marketplaceId' {marketPlaceId} is not supported. Promoted Listings with CPC funding model is supported only on these marketplaces: {supportedMarketplaces}."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}": {
- "get": {
- "tags": [
- "campaign"
- ],
- "description": "This method retrieves the details of a single campaign, as specified with the campaign_id query parameter. This method returns all the details of a campaign (including the campaign's the selection rules), except the for the listing IDs or inventory reference IDs included in the campaign. These IDs are returned by getAds.
Call getCampaigns to retrieve a list of the seller's campaign IDs.
",
- "operationId": "getCampaign",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Campaign"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developers support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "delete": {
- "tags": [
- "campaign"
- ],
- "description": "This method deletes the campaign specified by the campaign_id query parameter.
Note: You can only delete campaigns that have ended.
Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.",
- "operationId": "deleteCampaign",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35056": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The state of the campaign cannot be changed as requested."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/end": {
- "post": {
- "tags": [
- "campaign"
- ],
- "description": "This method ends an active (RUNNING) or paused campaign. Specify the campaign you want to end by supplying its campaign ID in a query parameter. Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.
",
- "operationId": "endCampaign",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35056": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The state of the campaign cannot be changed as requested."
- },
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/find_campaign_by_ad_reference": {
- "get": {
- "tags": [
- "campaign"
- ],
- "description": "This method retrieves the campaigns containing the listing that is specified using either a listing ID, or an inventory reference ID and inventory reference type pair. The request accepts either a listing_id, or an inventory_reference_id and inventory_reference_type pair, as used in the Inventory API.
eBay listing IDs are generated by either the Trading API or the Inventory API when you create a listing.
An inventory reference ID can be either a seller-defined SKU or inventoryItemGroupKey, as specified in the Inventory API.
Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
- "operationId": "findCampaignByAdReference",
- "parameters": [
- {
- "name": "inventory_reference_id",
- "in": "query",
- "description": "The seller's inventory reference ID of the listing to be used to find the campaign in which it is associated. This will either be a seller-defined SKU value or inventory item group ID, depending on the reference type specified. You must always pass in both inventory_reference_id and inventory_reference_type.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "inventory_reference_type",
- "in": "query",
- "description": "The type of the seller's inventory reference ID, which is a listing or group of items. You must always pass in both inventory_reference_id and inventory_reference_type.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "listing_id",
- "in": "query",
- "description": "Identifier of the eBay listing associated with the ad.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Campaigns"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35013": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID {listingId} is not valid."
- },
- "35014": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID is required for this call."
- },
- "35031": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A 'listing_id' or an 'inventory_reference_id' and 'inventory_reference_type' is required for this call."
- },
- "35032": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A 'listing_id' and an 'inventory_reference_id' cannot be used together in the same call. To use both in a campaign, you must submit two calls."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/get_campaign_by_name": {
- "get": {
- "tags": [
- "campaign"
- ],
- "description": "This method retrieves the details of a single campaign, as specified with the campaign_name query parameter. Note that the campaign name you specify must be an exact, case-sensitive match of the name of the campaign you want to retrieve.Call getCampaigns to retrieve a list of the seller's campaign names.
",
- "operationId": "getCampaignByName",
- "parameters": [
- {
- "name": "campaign_name",
- "in": "query",
- "description": "The name of the campaign.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Campaign"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35019": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Campaign name is required for this call."
- },
- "35020": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
- },
- "35023": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
- },
- "35046": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found with the name {campaign_name}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/launch": {
- "post": {
- "tags": [
- "campaign"
- ],
- "description": "This method launches a Promoted Listings Advanced campaign created using the setupQuickCampaign method that is in DRAFT status. This changes the campaign status to RUNNING or SCHEDULED, based on its specified start date. Specify the campaign you wish to launch by supplying its campaign_id as a path parameter in the call URI.
Use the getCampaigns method to retrieve the campaign_id and the campaign status for all the seller's campaigns.",
- "operationId": "launchCampaign",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign.
Note: The campaign ID value used here must be for a PLA campaign in DRAFT status. For PLA campaigns created with the setupQuickCampaign method, the getCampaign URI for that campaign is returned in the Location response header. That URI will include the campaign_id value, which you will pass in as a path parameter in the launchCampaign method. ",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35021": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign with the name of {campaignName} already exists. Please provide a different name."
- },
- "35043": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign status of {campaignStatus} is either invalid or not supported for this operation."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- }
- }
- }
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35067": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The seller must accept the Promoted Listings terms and conditions. Please accept Promoted Listings terms and conditions by visiting this link {userAgreementLink} ."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/pause": {
- "post": {
- "tags": [
- "campaign"
- ],
- "description": "This method pauses an active (RUNNING) campaign. You can restart the campaign by calling resumeCampaign, as long as the campaign's end date is in the future.
Note: The listings associated with a paused campaign cannot be added into another campaign.
Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.
",
- "operationId": "pauseCampaign",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "35056": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The state of the campaign cannot be changed as requested."
- },
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
+ }
},
- "/ad_campaign/{campaign_id}/resume": {
- "post": {
- "tags": [
- "campaign"
- ],
- "description": "This method resumes a paused campaign, as long as its end date is in the future. Supply the campaign_id for the campaign you want to restart as a query parameter in the request. Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.
",
- "operationId": "resumeCampaign",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
+ "components": {
+ "schemas": {
+ "Ad": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model. This ID is created after a successful createAdGroup call, and all ad groups must be associated with a CPC campaign."
+ },
+ "adId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID that is generated when the ad is created."
+ },
+ "adStatus": {
+ "type": "string",
+ "description": "The current status of the CPC ad.
Valid Values:Note: This type only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model. For implementation help, refer to eBay API documentation"
+ },
+ "alerts": {
+ "type": "array",
+ "description": "An array containing alert messages for the ad.",
+ "items": {
+ "$ref": "#/components/schemas/Alert"
+ }
+ },
+ "bidPercentage": {
+ "type": "string",
+ "description": "The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
This is default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.
Note:This field will always be returned for campaigns that use the Cost Per Sale (CPS) funding model. It will not be returned for campaigns that use the Cost Per Click (CPC) funding model.
Note: This field has a minimum value of 2.0 and a maximum value of 100.0."
+ },
+ "inventoryReferenceId": {
+ "type": "string",
+ "description": "An ID that identifies a single-item listing or multiple-variation listing that is managed with the Inventory API. The inventory reference ID is a seller-defined value that can be either an SKU for a single-item listing or an inventoryItemGroupKey for a multiple-value listing.
An inventoryItemGroupKey is a value that the seller defines to indicate a listing that's the parent of an inventory item group (a multiple-variation listing, such as a listing for a shirt that's available in multiple sizes and colors).
This field is only returned if the ad is associated with a SKU or an inventory item group value.
"
+ },
+ "inventoryReferenceType": {
+ "type": "string",
+ "description": "The enumeration value returned here indicates the type of listing the inventoryReferenceId references. The value returned here will be INVENTORY_ITEM for a single-variation listing, or INVENTORY_ITEM_GROUP for a multiple-variation listing. This field is only returned if the ad is associated with a SKU or an inventory item group value.
For implementation help, refer to eBay API documentation"
+ },
+ "listingId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID that is generated when a listing is created."
+ }
+ },
+ "description": "A type that defines the fields for an ad."
+ },
+ "AdGroup": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model."
+ },
+ "adGroupStatus": {
+ "type": "string",
+ "description": "An enumeration value representing the current status of the ad group.
Valid Values: For implementation help, refer to eBay API documentation"
+ },
+ "defaultBid": {
+ "description": "A bid amount that applies to all of the keywords in an ad group that do not have individual bids. For all keywords without individual bids, the default bid is the amount that the seller will pay per click for the listings in the ad group in the promoted listings campaign.
Valid Values: 0.5, 0.75",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "name": {
+ "type": "string",
+ "description": "The seller-defined name of the ad group."
+ }
+ },
+ "description": "A container for the details of an existing ad group.
An ad group can be added to a campaign that uses the Cost Per Click (CPC) funding model. A campaign may have multiple ad groups. All listings that are promoted in the campaign are included in the ad group.
Note: This type only applies to the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model."
+ },
+ "AdGroupPagedCollectionResponse": {
+ "type": "object",
+ "properties": {
+ "adGroups": {
+ "type": "array",
+ "description": "The details of existing ad groups, such as the name, ID, and status of the ad groups.",
+ "items": {
+ "$ref": "#/components/schemas/AdGroup"
+ }
+ },
+ "href": {
+ "type": "string",
+ "description": "The URI of the current page of results from the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Default: 0
Note: The items in a paginated result set use a zero-based list, where the first item in the list has an offset of 0.",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results."
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of items retrieved in the result set.
Note: If no items are found, this field is returned with a value of 0.",
+ "format": "int32"
+ }
+ },
+ "description": "A container for the details of a paged collection of ad groups.
Note: This type only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model."
+ },
+ "AdIds": {
+ "type": "object",
+ "properties": {
+ "adIds": {
+ "type": "array",
+ "description": "A list of ad IDs. Only one ad can be deleted per operation and only one adId value will be returned.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This type is a container for a list of ad IDs."
+ },
+ "AdPagedCollectionResponse": {
+ "type": "object",
+ "properties": {
+ "ads": {
+ "type": "array",
+ "description": "The list of ads that matched the request criteria.",
+ "items": {
+ "$ref": "#/components/schemas/Ad"
+ }
+ },
+ "href": {
+ "type": "string",
+ "description": "The URI of the current page of results from the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.Default: 10",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the next page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be increased to retrieve the next page of results.
Max length: 2048"
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first result on the current page. This value can be set in the request with the offset query parameter. If the offset value is not set, it defaults to zero.
Default: 0
Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results.
Max length: 2048"
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
+ "format": "int32"
+ }
+ },
+ "description": "This type defines the fields that paginate the ads returned by the request. The entire result set consists of 0 or more sequenced response pages, where each page consists of 0 or more items from the complete result set."
+ },
+ "AdReference": {
+ "type": "object",
+ "properties": {
+ "adId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for an ad. This ID is generated when an ad is created."
+ },
+ "href": {
+ "type": "string",
+ "description": "The getAd URI of an ad. You can use this URI to retrieve the ad."
+ }
+ },
+ "description": "This type defines the fields for an ad ID and its associated URL."
+ },
+ "AdReferences": {
+ "type": "object",
+ "properties": {
+ "ads": {
+ "type": "array",
+ "description": "A list of ad IDs. An ad ID is generated for each successfully created ad. Only one ad can be created per operation.",
+ "items": {
+ "$ref": "#/components/schemas/AdReference"
+ }
+ }
+ },
+ "description": "This type is a container for a list of ad IDs and their associated URIs."
+ },
+ "AdResponse": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for an ad group in a priority strategy campaign that uses the Cost Per Click (CPC) funding model.Note: This field will always be returned for campaigns that use the CPC funding model. It will not be returned for campaigns that use the Cost Per Sale (CPS) funding model."
+ },
+ "adId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for an ad. This ID is generated when an ad is created.Note:This field is only returned when an ad is successfully created for the corresponding listing."
+ },
+ "errors": {
+ "type": "array",
+ "description": "An array of errors associated with the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "href": {
+ "type": "string",
+ "description": "The getAd URI that points to the ad.Note:This field is only returned when an ad is successfully created for the corresponding listing."
+ },
+ "listingId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for a listing that is generated when the listing is created."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "An HTTP status code indicating if the corresponding ad was successfully created or not. 200 Successful should be returned for successfully created ads.Note:A status code is returned for each ad that the seller creates, or attempts to create.",
+ "format": "int32"
+ }
+ },
+ "description": "This type defines the fields returned in an ad response."
+ },
+ "AdUpdateResponse": {
+ "type": "object",
+ "properties": {
+ "adId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID that is generated when the ad is created."
+ },
+ "errors": {
+ "type": "array",
+ "description": "A list of errors associated with the specified listing ID.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "href": {
+ "type": "string",
+ "description": "The URI for the ad, which can be used to retrieve the ad."
+ },
+ "listingId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID that is generated when the listing is created."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "An HTTP status code that indicates the response-status of the request.",
+ "format": "int32"
+ }
+ },
+ "description": "A type that contains the fields for the ad update response."
+ },
+ "AdUpdateStatusByListingIdResponse": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model."
+ },
+ "errors": {
+ "type": "array",
+ "description": "A list of errors associated with the specified listing ID.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "href": {
+ "type": "string",
+ "description": "The URI for the ad, which can be used to retrieve the ad."
+ },
+ "listingId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID that is generated when the listing is created."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "An HTTP status code that indicates the response-status of the request.",
+ "format": "int32"
+ }
+ },
+ "description": "A type that contains the fields for the ad update status by listing ID response."
+ },
+ "AdUpdateStatusResponse": {
+ "type": "object",
+ "properties": {
+ "adId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID that is generated when the ad is created."
+ },
+ "errors": {
+ "type": "array",
+ "description": "A list of errors associated with the specified listing ID.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "href": {
+ "type": "string",
+ "description": "The URI for the ad, which can be used to retrieve the ad."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "An HTTP status code that indicates the response-status of the request.",
+ "format": "int32"
+ }
+ },
+ "description": "A type that contains the fields for the ad update status response."
+ },
+ "AdditionalInfo": {
+ "type": "object",
+ "properties": {
+ "infoType": {
+ "type": "string",
+ "description": "The type of additional information provided for the suggested keyword.
Valid Value: KEYWORD_INSIGHTS For implementation help, refer to eBay API documentation"
+ },
+ "metrics": {
+ "type": "array",
+ "description": "A list of additional data provided for the suggested keyword.",
+ "items": {
+ "$ref": "#/components/schemas/AdditionalInfoData"
+ }
+ }
+ },
+ "description": "A type that provides additional information for suggested keywords."
+ },
+ "AdditionalInfoData": {
+ "type": "object",
+ "properties": {
+ "metricKey": {
+ "type": "string",
+ "description": "The metric used to provide additional information for the suggested keyword.
Valid Values: ACTIVE_SELLER_COUNTSEARCH_VOLUME
For implementation help, refer to eBay API documentation"
+ },
+ "value": {
+ "type": "string",
+ "description": "The data provided for the specified metric.
Note: All metric data is compiled for the marketplace associated with the specified campaign ID."
+ }
+ },
+ "description": "A type that defines the data produced for additional information about suggested keywords."
+ },
+ "Ads": {
+ "type": "object",
+ "properties": {
+ "ads": {
+ "type": "array",
+ "description": "A list of ad IDs. An ad ID is generated for each successfully created ad.",
+ "items": {
+ "$ref": "#/components/schemas/Ad"
+ }
+ }
+ },
+ "description": "This type defines the container for an array of ads."
+ },
+ "Alert": {
+ "type": "object",
+ "properties": {
+ "alertType": {
+ "type": "string",
+ "description": "The type of alert message. For example, an invalid bid percentage. For implementation help, refer to eBay API documentation"
+ },
+ "details": {
+ "type": "array",
+ "description": "A description of the alert including dimensions and aspects.",
+ "items": {
+ "$ref": "#/components/schemas/AlertDetails"
+ }
+ }
+ },
+ "description": "A type that contains the alert message fields for the ad."
+ },
+ "AlertDetails": {
+ "type": "object",
+ "properties": {
+ "dimension": {
+ "description": "The dimension information of the alert including keys and values.",
+ "$ref": "#/components/schemas/AlertDimension"
+ },
+ "aspect": {
+ "description": "The aspect information of the alert including keys and values.",
+ "$ref": "#/components/schemas/Aspect"
+ }
+ },
+ "description": "A type that contains the alert detail fields."
+ },
+ "AlertDimension": {
+ "type": "object",
+ "properties": {
+ "key": {
+ "type": "string",
+ "description": "The key field of the applied dimension. For example, the marketplace Id. For implementation help, refer to eBay API documentation"
+ },
+ "value": {
+ "type": "string",
+ "description": "The value field of the applied dimension. For example, if the key is a MARKETPLACE_ID, the value would be from MarketplaceIdEnum."
+ }
+ },
+ "description": "A type that contains the dimension fields."
+ },
+ "Amount": {
+ "type": "object",
+ "properties": {
+ "currency": {
+ "type": "string",
+ "description": "The base currency applied to the value field to establish a monetary amount.
The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD For implementation help, refer to eBay API documentation"
+ },
+ "value": {
+ "type": "string",
+ "description": "The monetary amount in the specified currency.
Required in the amount type."
+ }
+ },
+ "description": "A complex type that describes the value of a monetary amount as represented by a global currency."
+ },
+ "Aspect": {
+ "type": "object",
+ "properties": {
+ "key": {
+ "type": "string",
+ "description": "The type of the aspect. For example, MINIMUM_REQUIRED. For implementation help, refer to eBay API documentation"
+ },
+ "value": {
+ "type": "string",
+ "description": "The value of the aspect. For example, if the aspect is a percentage, a value of '2.0' would equal 2%."
+ }
+ },
+ "description": "A type that contains the aspect fields."
+ },
+ "BaseResponse": {
+ "type": "object",
+ "properties": {
+ "warnings": {
+ "type": "array",
+ "description": "The container for any warning error messages generated by the request. Warnings are not fatal in that they do not prevent the call from running and returning a response, but they should be reviewed to ensure your requests are returning the responses you expect.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type defines the fields for any warning error messages."
+ },
+ "BidPreference": {
+ "type": "object",
+ "properties": {
+ "maxCpc": {
+ "description": "The maximum amount for which the eBay suggested bid can be adjusted. This value represents the most a seller is willing to pay for each click on their ad. The adjusted bid will never exceed this amount.
This field is required for smart targeting campaigns.
Note: The maximum cost-per-click has a minimum value of 0.02 and a maximum value of 100.",
+ "$ref": "#/components/schemas/MaxCpc"
+ }
+ },
+ "description": "This type indicates the bidding preferences of a Smart Targeting campaign.
Note: This type is only supported for CPC funding model campaigns with on-site channels."
+ },
+ "Budget": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "The allocated budget amount for a CPC Promoted Listings campaign.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "budgetStatus": {
+ "type": "string",
+ "description": "The budget status for a CPC Promoted Listings campaign. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A container for the budget details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model.
Note: This container will only be returned for campaigns using the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model."
+ },
+ "BudgetRecommendationResponse": {
+ "type": "object",
+ "properties": {
+ "budget": {
+ "description": "The allocated daily budget for the Cost Per Click (CPC) Promoted Listings campaign.",
+ "$ref": "#/components/schemas/CampaignBudget"
+ },
+ "campaignId": {
+ "type": "string",
+ "description": "The unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created."
+ },
+ "channels": {
+ "type": "array",
+ "description": "The channel for the campaign. This value indicates whether the campaign is an Onsite or Offsite advertising campaign.
Valid Values:",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ }
+ },
+ "description": "This type indicates the suggested daily keyword budget for an offsite campaign."
+ },
+ "BudgetRequest": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "The allocated budget amount for a CPC Promoted Listings campaign. Both the currency and value must be specified.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "A container for the budget details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model.
Note: This container will only be returned for campaigns using the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model."
+ },
+ "BulkAdResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "This array displays the list of ads that were successfully created. For any ads that were not created successfully, the errors array may provide more detail about why creation of one or more ads failed.",
+ "items": {
+ "$ref": "#/components/schemas/AdResponse"
+ }
+ }
+ },
+ "description": "This type defines the fields for the create ads in bulk response."
+ },
+ "BulkAdUpdateResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "A set of ad listings processed by the call.",
+ "items": {
+ "$ref": "#/components/schemas/AdUpdateResponse"
+ }
+ }
+ },
+ "description": "A type that defines the fields for updated ads in the bulk response."
+ },
+ "BulkAdUpdateStatusByListingIdResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "An array of processed ad listings in bulk.",
+ "items": {
+ "$ref": "#/components/schemas/AdUpdateStatusByListingIdResponse"
+ }
+ }
+ },
+ "description": "A type that defines the fields for the updated ad status in the bulk response."
+ },
+ "BulkAdUpdateStatusResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "An array of processed ad listings in bulk.",
+ "items": {
+ "$ref": "#/components/schemas/AdUpdateStatusResponse"
+ }
+ }
+ },
+ "description": "A type that defines the fields for the updated ad status in the bulk response."
+ },
+ "BulkCreateAdRequest": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "An array of listing IDs and their associated bid percentages, which the request uses to create ads in bulk. This request accepts both listing IDs, as generated by the Inventory API, and an item IDs, as used in the eBay Traditional API set (e.g., the Trading and Finding APIs).
Maximum: 500 IDs per call",
+ "items": {
+ "$ref": "#/components/schemas/CreateAdRequest"
+ }
+ }
+ },
+ "description": "This type defines the fields for the create ads in bulk by listing IDs."
+ },
+ "BulkCreateAdsByInventoryReferenceRequest": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "A list of inventory reference ID and inventory reference type pairs, and the bid percentage, which the call uses to create ads in bulk.",
+ "items": {
+ "$ref": "#/components/schemas/CreateAdsByInventoryReferenceRequest"
+ }
+ }
+ },
+ "description": "This type defines the fields used to create ads in bulk by inventory reference IDs."
+ },
+ "BulkCreateAdsByInventoryReferenceResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "This array displays the list of ads that were successfully created. For any ads that were not created successfully, the errors array may provide more detail about why creation of one or more ads failed.",
+ "items": {
+ "$ref": "#/components/schemas/CreateAdsByInventoryReferenceResponse"
+ }
+ }
+ },
+ "description": "This type defines the response fields used by the bulkCreateAdsByInventoryReference method."
+ },
+ "BulkCreateKeywordRequest": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "This array is used to pass in multiple keywords for one or more ad groups that belong to a campaign that uses the Cost Per Click (CPC) funding model. Up to {max value} keywords can be created with one call.",
+ "items": {
+ "$ref": "#/components/schemas/CreateKeywordRequest"
+ }
+ }
+ },
+ "description": "A type that contains the fields for the bulk request to create keywords."
+ },
+ "BulkCreateKeywordResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "A list of keywords that have been processed by the request.",
+ "items": {
+ "$ref": "#/components/schemas/KeywordResponse"
+ }
+ }
+ },
+ "description": "A type that contains the response fields for the bulk request to create keywords."
+ },
+ "BulkCreateNegativeKeywordRequest": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "This array is used to pass in multiple negative keywords for one or more ad groups that belong to a campaign that uses the Cost Per Click (CPC) funding model.",
+ "items": {
+ "$ref": "#/components/schemas/CreateNegativeKeywordRequest"
+ }
+ }
+ },
+ "description": "A type that contains the fields for the bulk request to create negative keywords."
+ },
+ "BulkCreateNegativeKeywordResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "A list of negative keywords that have been processed by the request.",
+ "items": {
+ "$ref": "#/components/schemas/NegativeKeywordResponse"
+ }
+ }
+ },
+ "description": "A type that contains the response fields for the bulk request to create negative keywords."
+ },
+ "BulkDeleteAdRequest": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "An array of the listing IDs that identify the ads to remove.",
+ "items": {
+ "$ref": "#/components/schemas/DeleteAdRequest"
+ }
+ }
+ },
+ "description": "This type defines the fields that the call uses to remove ads in bulk."
+ },
+ "BulkDeleteAdResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "An array of the ads that were deleted by the bulkDeleteAdsByListingId request, including information associated with each individual delete request.",
+ "items": {
+ "$ref": "#/components/schemas/DeleteAdResponse"
+ }
+ }
+ },
+ "description": "This type defines a container that lists the ads that bulkDeleteAdsByListingId deleted."
+ },
+ "BulkDeleteAdsByInventoryReferenceRequest": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "A list of inventory referenceID and inventory reference type pairs that specify the set of ads to remove in bulk.",
+ "items": {
+ "$ref": "#/components/schemas/DeleteAdsByInventoryReferenceRequest"
+ }
+ }
+ },
+ "description": "This type defines the request fields that bulkDeleteAdsByInventoryReference uses to delete ads in bulk."
+ },
+ "BulkDeleteAdsByInventoryReferenceResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "An array of the ads that were deleted by the bulkDeleteAdsByInventoryReference request, including information associated with each individual delete request.",
+ "items": {
+ "$ref": "#/components/schemas/DeleteAdsByInventoryReferenceResponse"
+ }
+ }
+ },
+ "description": "This type defines a container that lists the ads that bulkDeleteAdsByInventoryReference deleted."
+ },
+ "BulkUpdateAdStatusByListingIdRequest": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "An array of listing IDs and bid percentages.",
+ "items": {
+ "$ref": "#/components/schemas/UpdateAdStatusByListingIdRequest"
+ }
+ }
+ },
+ "description": "A type that defines the fields for the BulkUpdateAdStatusByListingId request."
+ },
+ "BulkUpdateAdStatusRequest": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "An array of listing IDs and bid percentages.",
+ "items": {
+ "$ref": "#/components/schemas/UpdateAdStatusRequest"
+ }
+ }
+ },
+ "description": "A type that defines the fields for the BulkUpdateAdStatus request."
+ },
+ "BulkUpdateAdsByInventoryReferenceResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "A list of inventory references that were processed from the request.",
+ "items": {
+ "$ref": "#/components/schemas/UpdateAdsByInventoryReferenceResponse"
+ }
+ }
+ },
+ "description": "A type that defines the fields for the BulkUpdateAdStatusByInventoryReference response."
+ },
+ "BulkUpdateKeywordRequest": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "Use this array to update the bid values and/or statuses of one or more existing keywords.",
+ "items": {
+ "$ref": "#/components/schemas/UpdateKeywordByKeywordIdRequest"
+ }
+ }
+ },
+ "description": "A type that defines the fields for the BulkUpdateKeyword request."
+ },
+ "BulkUpdateKeywordResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "A list of keywords that have been processed from the bulk request.",
+ "items": {
+ "$ref": "#/components/schemas/UpdateKeywordResponse"
+ }
+ }
+ },
+ "description": "A type that defines the fields for the BulkUpdateKeyword response."
+ },
+ "BulkUpdateNegativeKeywordRequest": {
+ "type": "object",
+ "properties": {
+ "requests": {
+ "type": "array",
+ "description": "An array to update the statuses of one or more existing negative keywords.",
+ "items": {
+ "$ref": "#/components/schemas/UpdateNegativeKeywordIdRequest"
+ }
+ }
+ },
+ "description": "A type that defines the fields for the BulkUpdateNegativeKeyword request."
+ },
+ "BulkUpdateNegativeKeywordResponse": {
+ "type": "object",
+ "properties": {
+ "responses": {
+ "type": "array",
+ "description": "A list of negative keywords that have been processed from the bulk request.",
+ "items": {
+ "$ref": "#/components/schemas/UpdateNegativeKeywordResponse"
+ }
+ }
+ },
+ "description": "A type that defines the fields for the BulkUpdateNegativeKeyword response."
+ },
+ "Campaign": {
+ "type": "object",
+ "properties": {
+ "alerts": {
+ "type": "array",
+ "description": "This array contains alert messages for the campaign.",
+ "items": {
+ "$ref": "#/components/schemas/Alert"
+ }
+ },
+ "budget": {
+ "description": "The allocated budget for the Cost Per Click (CPC) Promoted Listings campaign.Note: This field will only be returned for campaigns using the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model.",
+ "$ref": "#/components/schemas/CampaignBudget"
+ },
+ "campaignCriterion": {
+ "description": "The selection rules (criterion) used to select the listings for a campaign. If you populate the campaignCriterion object in your createCampaign request, ads for the campaign are created by rule for the listings that meet the criteria you specify, and these ads are associated with the campaign.Note: This container is only returned for rules-based campaigns using the Cost Per Sale (CPS) funding model.",
+ "$ref": "#/components/schemas/CampaignCriterion"
+ },
+ "campaignId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created."
+ },
+ "campaignName": {
+ "type": "string",
+ "description": "A seller-defined name for the campaign. This value must be unique for the seller. You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters"
+ },
+ "campaignStatus": {
+ "type": "string",
+ "description": "Indicates the status of the campaign, such as RUNNING, PAUSED, and ENDED. For implementation help, refer to eBay API documentation"
+ },
+ "campaignTargetingType": {
+ "type": "string",
+ "description": "The targeting type of the campaign. This value indicates whether the campaign is a manual targeting or smart targeting ad campaign. For implementation help, refer to eBay API documentation"
+ },
+ "channels": {
+ "type": "array",
+ "description": "The channel for the campaign. This value indicates whether the campaign is an Onsite or Offsite advertising campaign.
Valid Values:",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "endDate": {
+ "type": "string",
+ "description": "The date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is omitted, the campaign will have no defined end date, and will not end until the seller makes a decision to end the campaign with an endCampaign call, or if they update the campaign at a later time with an end date."
+ },
+ "fundingStrategy": {
+ "description": "This container includes parameters that define an ad campaign funding strategy. The set of seller-configurable parameters depends on the selected fundingModel value.
Currently, the supported funding models are COST_PER_SALE (CPS) and COST_PER_CLICK (CPC). For onsite ads, the CPC model supports two bidding strategies: FIXED and DYNAMIC.",
+ "$ref": "#/components/schemas/FundingStrategy"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The ID of the eBay marketplace where the campaign is hosted. For implementation help, refer to eBay API documentation"
+ },
+ "startDate": {
+ "type": "string",
+ "description": "The date and time the campaign starts, in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller. On the date specified, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts after this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign. Call getCampaign to check the status of the campaign.
"
+ }
+ },
+ "description": "This type defines the fields that describe an ad campaign."
+ },
+ "CampaignAudience": {
+ "type": "object",
+ "properties": {
+ "audienceType": {
+ "type": "string",
+ "description": "This enum value indicates the audience type. For the complete list of audience types and their associated enum values, see AudienceTypeEnum. For implementation help, refer to eBay API documentation"
+ },
+ "code": {
+ "type": "string",
+ "description": "The unique code for an audience. "
+ },
+ "name": {
+ "type": "string",
+ "description": "The display name for an audience."
+ }
+ },
+ "description": "This is the object for a single email campaign audience."
+ },
+ "CampaignBudget": {
+ "type": "object",
+ "properties": {
+ "daily": {
+ "description": "The daily budget limit for the Cost Per Click (CPC) Promoted Listings campaign.
Required if the campaign's funding model is CPC.
This will be a dollar value. All clicks using the keywords defined for the campaign will go towards expending the daily budget. Once the daily budget is exceeded for the campaign, all Promoted Listings under the campaign will be turned off until the next day.
When running an offsite campaign, eBay may spend more or less than the seller's daily budget to capitalize on interested buyers, but will not exceed 2x the daily budget. The average over the course of the campaign will not exceed the provided daily budget. This value is used to calculate a total monthly budget by multiplying 30.4 by the provided daily budget. Over the course of the campaign, eBay will not charge more than this total budget per month.
If a campaign ends prematurely, however, the seller may be charged up to 2x their daily budget on a daily basis, as the campaign may have not had the chance to average the budget out over time.
Valid Values:",
+ "$ref": "#/components/schemas/Budget"
+ }
+ },
+ "description": "A type that defines the budget details for a Cost Per Click (CPC) Promoted Listings campaign."
+ },
+ "CampaignBudgetRequest": {
+ "type": "object",
+ "properties": {
+ "daily": {
+ "description": "The daily budget limit for a CPC Promoted Listings campaign.
When running an offsite campaign, eBay may spend more or less than the seller's daily budget to capitalize on interested buyers, but will not exceed 2x the daily budget. The average over the course of the campaign will not exceed the provided daily budget. This value is used to calculate a total monthly budget by multiplying 30.4 by the provided daily budget. Over the course of the campaign, eBay will not charge more than this total budget per month.
If a campaign ends prematurely, however, the seller may be charged up to 2x their daily budget on a daily basis, as the campaign may have not had the chance to average the budget out over time.",
+ "$ref": "#/components/schemas/BudgetRequest"
+ }
+ },
+ "description": "A container for the details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model."
+ },
+ "CampaignCriterion": {
+ "type": "object",
+ "properties": {
+ "autoSelectFutureInventory": {
+ "type": "boolean",
+ "description": "A field used to indicate whether listings shall be automatically added to, or removed from, a Promoted Listings campaign based on the rules that have been configured for the campaign.
If set to true, eBay adds all listings matching the campaign criterion to the campaign, including any new listings created from the items in a seller's inventory.
Default: false"
+ },
+ "criterionType": {
+ "type": "string",
+ "description": "This enum defines the criterion (selection rule) types. Currently, the only criterion type supported is INVENTORY_PARTITION, and you must specify this value if you manage your items with the Inventory API and you want to include items based on their inventory reference IDs.
Do not include this field if you manage your listings with Trading API/legacy model. For implementation help, refer to eBay API documentation"
+ },
+ "selectionRules": {
+ "type": "array",
+ "description": "This container shows all of the rules/inclusion filters used to add listings to the campaign. For information on using the contained fields, see Promoted Listing campaigns.",
+ "items": {
+ "$ref": "#/components/schemas/SelectionRule"
+ }
+ }
+ },
+ "description": "This type defines the fields for specifying the criterion (selection rule) settings of an ad campaign. If you populate the campaignCriterion object in your createCampaign request, ads for the campaign are created by rule for the listings that meet the criteria you specify, and these ads are associated with the newly created campaign."
+ },
+ "CampaignDTO": {
+ "type": "object",
+ "properties": {
+ "audiences": {
+ "type": "array",
+ "description": "The audiences that the email campaign is being sent to. See AudienceTypeEnum for a list of audience types.",
+ "items": {
+ "$ref": "#/components/schemas/CampaignAudience"
+ }
+ },
+ "creationDate": {
+ "type": "string",
+ "description": "The date and time that the email campaign was created, given in UTC format."
+ },
+ "emailCampaignId": {
+ "type": "string",
+ "description": "The unique eBay identifier for the email campaign assigned automatically when the email campaign is created."
+ },
+ "emailCampaignStatus": {
+ "type": "string",
+ "description": "The email campaign status. See EmailCampaignStatusEnum for information on statuses. For implementation help, refer to eBay API documentation"
+ },
+ "emailCampaignType": {
+ "type": "string",
+ "description": "The email campaign type. See CampaignTypeEnum for definitions of email campaign types. For implementation help, refer to eBay API documentation"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The eBay marketplace where the email campaign is active."
+ },
+ "modificationDate": {
+ "type": "string",
+ "description": "The date and time the email campaign was last modified, given in UTC format."
+ },
+ "scheduleDate": {
+ "type": "string",
+ "description": "The date and time that the email campaign newsletter is scheduled to send, given in UTC format."
+ },
+ "scheduleDateType": {
+ "type": "string",
+ "description": "The schedule type used for sending the email campaign. See ScheduleDateTypeEnum for available schedule types. For implementation help, refer to eBay API documentation"
+ },
+ "sentDate": {
+ "type": "string",
+ "description": "The date and time that the email campaign was last sent, given in UTC format."
+ },
+ "subject": {
+ "type": "string",
+ "description": "The email campaign subject line.."
+ }
+ },
+ "description": "email campaign instance body"
+ },
+ "CampaignPagedCollectionResponse": {
+ "type": "object",
+ "properties": {
+ "campaigns": {
+ "type": "array",
+ "description": "This array contains all of the seller's campaign that match the request criteria.",
+ "items": {
+ "$ref": "#/components/schemas/Campaign"
+ }
+ },
+ "href": {
+ "type": "string",
+ "description": "The URI of the current page of results from the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results.
Max length: 2048"
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of campaigns retrieved in the result set.
If no campaigns are found, this field is returned with a value of 0.",
+ "format": "int32"
+ }
+ },
+ "description": "This type defines the fields that paginate the campaigns returned by the request. The entire result set consists of 0 or more sequenced response pages, where each page consists of 0 or more items from the complete result set."
+ },
+ "Campaigns": {
+ "type": "object",
+ "properties": {
+ "campaigns": {
+ "type": "array",
+ "description": "This is an array of one or campaigns that match the listing or inventory item group specified in the request.",
+ "items": {
+ "$ref": "#/components/schemas/Campaign"
+ }
+ }
+ },
+ "description": "This type contains a list of campaigns."
+ },
+ "CloneCampaignRequest": {
+ "type": "object",
+ "properties": {
+ "campaignName": {
+ "type": "string",
+ "description": "A seller-defined name for the newly-cloned campaign. This value must be unique for the seller.
You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters"
+ },
+ "endDate": {
+ "type": "string",
+ "description": "The date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is omitted, the campaign will have no defined end date, and will not end until the seller makes a decision to end the campaign with an endCampaign call, or if they update the campaign at a later time with an end date."
+ },
+ "fundingStrategy": {
+ "description": "This container includes parameters that define an ad campaign funding strategy. The set of seller-configurable parameters depends on the selected fundingModel value.",
+ "$ref": "#/components/schemas/FundingStrategy"
+ },
+ "startDate": {
+ "type": "string",
+ "description": "The date and time the cloned campaign starts, in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller. On the date specified, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts after this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign. Call getCampaign to check the status of the campaign.
"
+ }
+ },
+ "description": "This type defines the fields needed for a clone-campaign request."
+ },
+ "CouponConfiguration": {
+ "type": "object",
+ "properties": {
+ "couponCode": {
+ "type": "string",
+ "description": "A unique code that buyers can use during checkout to receive a discount. The code must be unique across eBay.
The code must be from 8-15 alphanumeric characters and can contain no more than two dashes ( - ).
This is required when the discount type is CODED_COUPON."
+ },
+ "couponType": {
+ "type": "string",
+ "description": "This indicates the type of Coded Coupon discount, and is required when the discount type is CODED_COUPON.
Supported types:- PRIVATE_SINGLE_SELLER_COUPON: Anyone can use and share the coupon code, but it isn't posted on eBay.
- PUBLIC_SINGLE_SELLER_COUPON: Anyone can find the coupon code on eBay and use it.
For implementation help, refer to eBay API documentation"
+ },
+ "maxCouponRedemptionPerUser": {
+ "type": "integer",
+ "description": "This sets the limit on the number of times a buyer can use this coupon. The range of values is 1-10. If no value is provided, a buyer can use the coupon an unlimited number of times.",
+ "format": "int32"
+ }
+ },
+ "description": "This container defines a coded coupon discount. It is required if the discount type is CODED_COUPON."
+ },
+ "CreateAdGroupRequest": {
+ "type": "object",
+ "properties": {
+ "defaultBid": {
+ "description": "A bid amount that applies to all of the keywords in an ad group that do not have individual bids.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "name": {
+ "type": "string",
+ "description": "The seller-defined name of the ad group."
+ }
+ },
+ "description": "A type that defines the fields for the CreateAdGroup request."
+ },
+ "CreateAdRequest": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "A unique eBay-assigned identifier for an ad group in a campaign that uses the Cost Per Click (CPC) funding model.
Use the getAdGroups method to retrieve the ad group IDs for a seller.
Note: This field is required for manual targeting campaigns using the Cost Per Click (CPC) funding model."
+ },
+ "bidPercentage": {
+ "type": "string",
+ "description": "The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
Required if the campaign's funding model is Cost Per Sale (CPS).
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.
Note: This field has a minimum value of 2.0 and a maximum value of 100.0."
+ },
+ "listingId": {
+ "type": "string",
+ "description": "A unique identifier of an eBay listing."
+ }
+ },
+ "description": "This type defines the fields for the create ad request."
+ },
+ "CreateAdsByInventoryReferenceRequest": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "Note: This field is not currently in use. Ad groups are only applicable to priority strategy ad campaigns that use the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information."
+ },
+ "bidPercentage": {
+ "type": "string",
+ "description": "The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
Required if the campaign's funding model is Cost Per Sale (CPS).
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.
Note: This field has a minimum value of 2.0 and a maximum value of 100.0."
+ },
+ "inventoryReferenceId": {
+ "type": "string",
+ "description": "The unique identifier of a single-item listing or a multi-variation listing.
To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).
To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API."
+ },
+ "inventoryReferenceType": {
+ "type": "string",
+ "description": "This enumerated value indicates the type of item the inventoryReferenceId references.
The item can be either an INVENTORY_ITEM or an INVENTORY_ITEM_GROUP. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type defines the fields needed to create ads by inventory reference ID request."
+ },
+ "CreateAdsByInventoryReferenceResponse": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for an ad group in a priority strategy campaign that uses the Cost Per Click (CPC) funding model.Note: This field will always be returned for campaigns that use the CPC funding model. It will not be returned for campaigns that use the Cost Per Sale (CPS) funding model."
+ },
+ "ads": {
+ "type": "array",
+ "description": "A list of ad IDs. An ad ID is generated for each successfully created ad.",
+ "items": {
+ "$ref": "#/components/schemas/AdReference"
+ }
+ },
+ "errors": {
+ "type": "array",
+ "description": "An array of errors or warnings associated with the create-ads request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "inventoryReferenceId": {
+ "type": "string",
+ "description": "An ID that identifies a single-item listing or multiple-variation listing that is managed with the Inventory API. The inventory reference ID is a seller-defined value that can be either an SKU for a single-item listing or an inventoryItemGroupKey for a multiple-value listing.
"
+ },
+ "inventoryReferenceType": {
+ "type": "string",
+ "description": "Indicates the type of item the inventoryReferenceId references. The item can be either an INVENTORY_ITEM or an INVENTORY_ITEM_GROUP. For implementation help, refer to eBay API documentation"
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "An HTTP status code that indicates the response-status of the request. Check this code to see if the ads were successfully created.",
+ "format": "int32"
+ }
+ },
+ "description": "This type defines the fields returned when you create an ad by inventory reference ID."
+ },
+ "CreateCampaignRequest": {
+ "type": "object",
+ "properties": {
+ "budget": {
+ "description": "The allocated daily budget for the Cost Per Click (CPC) Promoted Listings campaign.
Required if the campaign funding model is CPC.",
+ "$ref": "#/components/schemas/CampaignBudgetRequest"
+ },
+ "campaignCriterion": {
+ "description": "This container is used if the seller wishes to create one or more rules for a rules-based campaign. If you populate the campaignCriterion object in your createCampaign request, ads for the campaign are created by rule for the listings that meet the criteria you specify, and these ads are associated with the campaign to be created.
Note: Rules-based listing selection is only applicable for general strategy campaigns using the Cost-Per-Sale (CPS) funding model.",
+ "$ref": "#/components/schemas/CampaignCriterion"
+ },
+ "campaignName": {
+ "type": "string",
+ "description": "A seller-defined name for the campaign. This value must be unique for the seller. You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters"
+ },
+ "campaignTargetingType": {
+ "type": "string",
+ "description": "The targeting type of the campaign. This value indicates whether the campaign is a manual targeting or smart targeting campaign.
If not value is specified, this field will default to MANUAL.
Note: This feature is only supported for on-site campaigns that use the Cost Per Click (CPC) funding model.
Valid Values:This field is required and must be set to SMART for a Smart Targeting campaign. For implementation help, refer to eBay API documentation"
+ },
+ "channels": {
+ "type": "array",
+ "description": "The channel for the campaign. This value indicates whether the advertising campaign is an Onsite or Offsite.
If no value is entered, this field will default to ON_SITE. Multiple channels are not supported.
Note: Channels is only applicable for campaigns that use the Cost Per Click (CPC) funding model.
Valid Values:This field is required and must be set to OFF_SITE for a Promoted Offsite campaign.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "endDate": {
+ "type": "string",
+ "description": "The date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is omitted, the campaign will have no defined end date, and will not end until the seller makes a decision to end the campaign with an endCampaign call, or if they update the campaign at a later time with an end date."
+ },
+ "fundingStrategy": {
+ "description": "This container includes parameters that define an ad campaign funding strategy. The set of seller-configurable parameters depends on the selected fundingModel value.",
+ "$ref": "#/components/schemas/FundingStrategy"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The ID of the eBay marketplace where the campaign is hosted. See the MarketplaceIdEnum type to get the appropriate enumeration value for the listing marketplace. For implementation help, refer to eBay API documentation"
+ },
+ "startDate": {
+ "type": "string",
+ "description": "The date and time the campaign starts, in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller. On the date specified, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts after this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign. Call getCampaign to check the status of the campaign.
"
+ }
+ },
+ "description": "This type defines the fields needed to create a campaign. To create a campaign, you need to specify a name, start and end dates, funding, marketplace, and optionally the criterion (selection rules)."
+ },
+ "CreateEmailCampaignRequest": {
+ "type": "object",
+ "properties": {
+ "audienceCodes": {
+ "type": "array",
+ "description": "An array of audience codes for the audiences of the email campaign. At least one audience code is required. There is no upper limit to the number of audience codes.
To retrieve seller audiences, call getAudiences. Use the code values in the response to populate audienceCodes.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of either an eBay category or a store category.
This field is used if a seller wants to apply an email campaign to a specific eBay category or store category. The categoryType determines whether the categoryId value is an eBay category or store category.
Use the Taxonomy API to retrieve eBay categories. To retrieve seller store categories, use the getStore call. Use the categoryId value of the desired category from the results as the value in the request.
itemSelectMode must be set to AUTO in order to use a category ID."
+ },
+ "categoryType": {
+ "type": "string",
+ "description": "This field must be set when applying an email campaign to a specific eBay category or store category. The enumeration value used indicates which type of category the categoryId belongs to. For implementation help, refer to eBay API documentation"
+ },
+ "emailCampaignType": {
+ "type": "string",
+ "description": "The email campaign type of the email campaign being created. There are six email campaigns that a user can create:WELCOME - an email sent automatically to new subscribers.ITEM_SHOWCASE - an email featuring new products & collections that the seller wants to highlight.COUPON - an email containing a coupon code and up to 4 items that this coupon can be applied to.ORDER_DISCOUNT - an email containing an order discount and up to 10 items that this discount can be applied to.SALE_EVENT - an email about a sale event and up to 10 items that the sale can be applied to.VOLUME_PRICING - an email containing up to 10 items that are eligible for volume pricing.
Note: emailCampaignType cannot be updated once the email campaign is created. For implementation help, refer to eBay API documentation"
+ },
+ "itemIds": {
+ "type": "array",
+ "description": "An array of unique identifiers for the listings displayed in an email campaign. Used if the seller wishes to select the eBay listings in the email campaign rather than have eBay automatically select them.
Call getSellerList to retrieve all seller listings. Each Item result contains an ItemID value. Use this value in itemIds to feature that listing.
The maximum number of itemIds for the COUPON campaign type is 4, and for every other campaign type is 10
itemSelectMode must be set to MANUAL in order to use this field.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "itemSelectMode": {
+ "type": "string",
+ "description": "Determines whether listings featured in an email campaign are selected by the seller or by eBay.
If itemSelectMode is set to AUTO, eBay automatically choses listings based on values set for sort, categoryType, categoryId, and priceRange.
If itemSelectMode is set to MANUAL, listings are set by the seller by populating the itemIds array.
Note: itemSelectMode is always set to AUTO for WELCOME email campaigns. For implementation help, refer to eBay API documentation"
+ },
+ "personalizedMessage": {
+ "type": "string",
+ "description": "The body of the email campaign. Accepts HTML and CSS.
Max length: 1000"
+ },
+ "priceRange": {
+ "description": "This container is used if the seller wants to apply the email campaign to listings based on a price range.
The priceRange container consists of the currency, gte, and lte fields.
\"gte\" stands for \"greater than or equal to\" and \"lte\" stands for \"less than or equal to\". Either gte, lte, or both must be used.
currency is a required field if including a price range. One of the three-digit currency codes from CurrencyCodeEnum must be specified.
Note: Use this object when the itemSelectMode is set to AUTO.",
+ "$ref": "#/components/schemas/PriceRange"
+ },
+ "promotionId": {
+ "type": "string",
+ "description": "The unique identifier of the discount used for an email campaign if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT. promotionSelectModeEnum must set to MANUAL if a discount is selected.
Call getPromotions to retrieve a list of the seller's discounts. Use the promotionId from an individual PromotionDetail in the result to populate the request."
+ },
+ "promotionSelectModeEnum": {
+ "type": "string",
+ "description": "The selection mode for the discount used if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT.
If promotionSelectModeEnum is set to AUTO, eBay will choose the discount to include in the email campaign. If set to MANUAL, the seller must specify the discount in the promotionId field. For implementation help, refer to eBay API documentation"
+ },
+ "scheduleDate": {
+ "type": "string",
+ "description": "The date and time that the email campaign newsletter will be sent, given in UTC format. Example: 2023-05-20T03:13:35Z
This field should be used if the seller wishes to send the email campaign on a future date. If no scheduleDate is set, the email campaign will send once it is created or updated."
+ },
+ "sort": {
+ "type": "string",
+ "description": "The sort rule is used to display the listings featured in the email campaign.
Sort rules are only used if itemSelectMode is set to AUTO. If itemSelectMode is MANUAL, listings are displayed in the order in which they are listed in the itemIds array. The following sort rules are available:ENDING_FIRST displays listings by ending date, from soonest to latest.LOWEST_PRICED displays listings by price, from lowest to highest.HIGHEST_PRICED displays listings by price, from highest to lowest.NEWLY_LISTED displays listings by date listed, with the newest first.
The default sort rule is NEWLY_LISTED. For implementation help, refer to eBay API documentation"
+ },
+ "subject": {
+ "type": "string",
+ "description": "The subject line of the email campaign.
Max length: 70"
+ }
+ },
+ "description": "create email campaign request payload"
+ },
+ "CreateEmailCampaignResponse": {
+ "type": "object",
+ "properties": {
+ "emailCampaignId": {
+ "type": "string",
+ "description": "The unique eBay-assigned identifier of the email campaign. It is generated automatically when the email campaign is created.
This value is returned unless there is an error."
+ },
+ "emailCampaignStatus": {
+ "type": "string",
+ "description": "The status of the email campaign.
ACTIVE is returned for email campaigns that have been successfully created but not been sent.
SENT is returned for email campaigns that have already been sent.
ERROR is returned when an email has not been successfully created. For implementation help, refer to eBay API documentation"
+ }
}
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35056": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The state of the campaign cannot be changed as requested."
- },
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
+ },
+ "CreateKeywordRequest": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "This adGroupId is created when an ad group is first created and associated with a campaign. This is the ad group that the corresponding keyword will be added to. This ad group must be a part of the campaign that is specified in the call URI. Use the getAdGroups method to retrieve the ad group IDs for a seller, and getKeywords to retrieve the keyword IDs for a seller's keywords."
+ },
+ "bid": {
+ "description": "This container is used to set the maximum bid for the keyword. Each time a listing is retrieved in search results using this keyword and clicked on, the seller will be charged, at most, this amount. Each click goes toward the daily budget set up for the CPC campaign. If the bid is not provided, then the default bid associated with the ad group is used.
Note: You can call the suggestBids method to retrieve the suggested bids for keywords.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "keywordText": {
+ "type": "string",
+ "description": "The text of the keyword. Keywords are not case sensitive and compound words can be used without additional encoding (for example, tennis ball).
Maximum number of characters: 100
Maximum number of words: 10"
+ },
+ "matchType": {
+ "type": "string",
+ "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A type that defines the fields for the CreateKeyword request."
+ },
+ "CreateNegativeKeywordRequest": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "This adGroupId is created when an ad group is first created and associated with a campaign. This is the ad group to which the corresponding negative keyword will be added.
Use the getAdGroups method to retrieve the ad group IDs for a seller.
Required if the negative keyword is being created at the ad group level."
+ },
+ "campaignId": {
+ "type": "string",
+ "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the set of negative keywords being created.
Use the getCampaigns method to retrieve campaign IDs.
Required if the negative keyword is being created at the ad group level."
+ },
+ "negativeKeywordMatchType": {
+ "type": "string",
+ "description": "A field that defines the match type for the negative keyword.
Note: Broad matching of negative keywords is not currently supported.
Valid Values: For implementation help, refer to eBay API documentation"
+ },
+ "negativeKeywordText": {
+ "type": "string",
+ "description": "The negative keyword text."
+ }
+ },
+ "description": "A type that defines the fields for the CreateNegativeKeyword request."
+ },
+ "CreateReportTask": {
+ "type": "object",
+ "properties": {
+ "additionalRecords": {
+ "type": "array",
+ "description": "A list of additional records that shall be included in the report, such as non-performing data.
Note: Additional records are only applicable to Promoted Listings priority strategy campaigns that use the Cost Per Click (CPC) funding model.
Valid Value: NON_PERFORMING_DATA",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "campaignIds": {
+ "type": "array",
+ "description": "A list of campaign IDs to be included in the report task. Use the getCampaigns method to retrieve a list of the current campaign IDs for a seller.
For general campaign strategy sellers, this field is required if the reportType is set to CAMPAIGN_PERFORMANCE_REPORT or CAMPAIGN_PERFORMANCE_SUMMARY_REPORT.
For priority strategy campaign sellers, leave this request field blank to retrieve the details for all campaigns associated with your account, or specify the campaign IDs for which you would like to retrieve the campaign-specific details.
Note: There is a maximum data limit that cannot be exceeded when generating reports. If this threshold is exceeded, the report will fail. Refer to Promoted Listings reporting in the Selling Integration Guide for details.
Maximum: 1,000 IDs
",
+ "items": {
+ "type": "string"
+ }
+ },
+ "channels": {
+ "type": "array",
+ "description": "The channel for the advertising campaign that will be included in the report task. This value indicates whether the data included in the report task is for an Onsite or Offsite advertising campaign.
If no value is entered, this field will default to ON_SITE. Multiple channels are not supported.
Note: Channels are only applicable for campaigns that use the Cost Per Click (CPC) funding model.
Valid Values:This field is required and must be set to OFF_SITE if the report is for a Offsite Ads campaign.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "dateFrom": {
+ "type": "string",
+ "description": "The date defining the start of the timespan covered by the report.
Format the timestamp as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock with local offset.
Note: The date specified cannot be a future date.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2021-03-15T13:00:00-07:00"
+ },
+ "dateTo": {
+ "type": "string",
+ "description": "The date defining the end of the timespan covered by the report.
As with the dateFrom field, format the timestamp as an ISO 8601 string.
Note: The date specified cannot be a future date. Additionally, the time specified must be a later time than that specified in the dateFrom field.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2021-03-17T13:00:00-07:00"
+ },
+ "dimensions": {
+ "type": "array",
+ "description": "The list of the dimensions applied to the report. A dimension is an attribute to which the report data applies. For example, if you set dimensionKey to campaign_id in a Campaign Performance Report, the data will apply to the entire ad campaign. For information on the dimensions and how to specify them, see Promoted Listings reporting.
",
+ "items": {
+ "$ref": "#/components/schemas/Dimension"
+ }
+ },
+ "fundingModels": {
+ "type": "array",
+ "description": "The funding model for the campaign that shall be included in the report.
Note: The default funding model for Promoted Listings reports is COST_PER_SALE.
Note: Multiple value support for the fundingModels array has been deprecated. See API Deprecation Status for information.
Valid Values:COST_PER_SALECOST_PER_CLICK
Required if the campaign funding model is Cost Per Click (CPC).",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "inventoryReferences": {
+ "type": "array",
+ "description": "You can use this field to supply an array of items to include in the report if you manage your inventory with the Inventory API.
This field is mutually exclusive with the listingIds field; if you populate this field, do not populate the listingIds field.
An inventory reference identifies an item in your inventory using a pair of values, where the inventoryReferenceId can be either a seller-defined SKU value or an inventoryItemGroupKey, where an inventoryItemGroupKey is seller-defined ID for an inventory item group (a multiple-variation listing).
Couple the inventoryReferenceId with an inventoryReferenceType identifier to fully identify an item in your inventory.
Maximum: 500 items
Required if you do not supply an array of listingId values or if you set reportType to INVENTORY_PERFORMANCE_REPORT.",
+ "items": {
+ "$ref": "#/components/schemas/InventoryReference"
+ }
+ },
+ "listingIds": {
+ "type": "array",
+ "description": "Use this field to supply an array of eBay listing IDs you want to include in the report.
Important: This field is mutually exclusive with the inventoryReferences field; if you populate this field, do not populate the inventoryReferences field.
For general campaign strategy sellers, this field is required if you do not supply an array of inventoryReferences values or if you set the reportType to LISTING_PERFORMANCE_REPORT.
For priority strategy campaign sellers, leave this field blank to retrieve the details for all listings associated with the specified campaign IDs (or all campaigns associated with your account, if no campaign IDs are specified), or specify the listing IDs for which you would like to retrieve the listing-specific details.
Note: There is a maximum data limit that cannot be exceeded when generating reports. If this threshold is exceeded, the report will fail. Refer to Promoted Listings reporting in the Selling Integration Guide for details.
Maximum: 500 listings",
+ "items": {
+ "type": "string"
+ }
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The unique identifier for the eBay marketplace on which the report is based. For implementation help, refer to eBay API documentation"
+ },
+ "metricKeys": {
+ "type": "array",
+ "description": "The list of metrics to be included in the report. Metrics are the quantitative measurements compiled into the report and the data returned is based on the specified dimension of the report. For example, if the dimension is campaign, the metrics for number of sales would be the number of sales in the campaign. However, if the dimension is listing, the number of sales represents the number of items sold in that listing.
For information on metric keys and how to set them, see Promoted Listings reporting.
Minimum: 1",
+ "items": {
+ "type": "string"
+ }
+ },
+ "reportFormat": {
+ "type": "string",
+ "description": "The file format of the report. Currently, the only supported format is TSV_GZIP, which is a gzip file with tab separated values. For implementation help, refer to eBay API documentation"
+ },
+ "reportType": {
+ "type": "string",
+ "description": "The type of report to be generated, such as ACCOUNT_PERFORMANCE_REPORT or CAMPAIGN_PERFORMANCE_REPORT.
Note: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending.
Maximum: 1 For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type defines the rules that govern the generation of a report task and the criteria that's used to create the report. The report-generation rules include the starting and ending dates for the report. Report-task criteria includes the report dimensions, metrics, listings covered in the report, and so on. For information on the required and optional fields for each report type, see Promoted Listings reporting."
+ },
+ "DeleteAdRequest": {
+ "type": "object",
+ "properties": {
+ "listingId": {
+ "type": "string",
+ "description": "A unique eBay-assigned identifier for a listing that is generated when the listing is created. Note: This request accepts both listing IDs, as generated by the Inventory API, and an item IDs, as used in the eBay Traditional API set (e.g., the Trading and Finding APIs).
"
+ }
+ },
+ "description": "This type defines the fields used in a delete-ad request."
+ },
+ "DeleteAdResponse": {
+ "type": "object",
+ "properties": {
+ "adId": {
+ "type": "string",
+ "description": "The unique identifier of the ad that was deleted, or the ad that the seller attempted to delete."
+ },
+ "errors": {
+ "type": "array",
+ "description": "An array of the errors or warnings associated with the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "listingId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for a listing that is generated when the listing is created."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "An HTTP status code that indicates the response-status of the request. Check this code to see if the ad was successfully deleted.Note:A status code is returned for each ad that the seller deletes, or attempts to delete.",
+ "format": "int32"
+ }
+ },
+ "description": "This type defines the fields returned in a delete-ad response."
+ },
+ "DeleteAdsByInventoryReferenceRequest": {
+ "type": "object",
+ "properties": {
+ "inventoryReferenceId": {
+ "type": "string",
+ "description": "The unique identifier of a single-item listing or a multi-variation listing.
To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).
To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API."
+ },
+ "inventoryReferenceType": {
+ "type": "string",
+ "description": "This enumerated value indicates the type of item the inventoryReferenceId references.
The item can be either an INVENTORY_ITEM or an INVENTORY_ITEM_GROUP. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type defines the fields needed to delete an ad by its inventory reference ID. You must always supply both inventory_reference_id and inventory_reference_type."
+ },
+ "DeleteAdsByInventoryReferenceResponse": {
+ "type": "object",
+ "properties": {
+ "adIds": {
+ "type": "array",
+ "description": "The unique identifier of the ad that was deleted, or the ad that the seller attempted to delete.Note:Although the field name is plural and it is an array, only one ad ID will be returned here since there can be only one ad per listing.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "errors": {
+ "type": "array",
+ "description": "The container for the errors associated with the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "inventoryReferenceId": {
+ "type": "string",
+ "description": "The inventory reference ID is a seller-defined SKU value for a single-item listing, or a seller-defined identifier for an inventory item group. Both of these values are defined when using the Inventory API, and an inventory item group is used to create a multiple-variation listing."
+ },
+ "inventoryReferenceType": {
+ "type": "string",
+ "description": "The enumeration value returned here indicates if the ad was for a single-variation listing or a multiple-variation listing. For implementation help, refer to eBay API documentation"
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "An HTTP status code indicating if the corresponding ad was successfully deleted or not. 200 Successful should be returned for successfully deleted ads. Note:A status code is returned for each ad that the seller deletes, or attempts to delete.",
+ "format": "int32"
+ }
+ },
+ "description": "This type defines the fields returned by request to delete a set of ads by inventory reference ID."
+ },
+ "DeleteEmailCampaignResponse": {
+ "type": "object",
+ "properties": {
+ "emailCampaignId": {
+ "type": "string",
+ "description": "The unique eBay-assigned ID for the email campaign that is generated when the email campaign is created."
+ }
}
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
+ },
+ "Dimension": {
+ "type": "object",
+ "properties": {
+ "annotationKeys": {
+ "type": "array",
+ "description": "A list of annotations associated with the dimension of the report.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "dimensionKey": {
+ "type": "string",
+ "description": "The name of the dimension on which the report is based. A dimension is an attribute to which the report data applies.
"
+ }
+ },
+ "description": "This type defines the annotation and dimension key used by the report. For information on how to set these values, see Promoted Listings reporting."
+ },
+ "DimensionKeyAnnotation": {
+ "type": "object",
+ "properties": {
+ "annotationKey": {
+ "type": "string",
+ "description": "An annotation key associated with the dimension."
+ },
+ "dataType": {
+ "type": "string",
+ "description": "The data type of the annotation key value. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type defines the annotation values associated with a dimension. Annotations are metadata of the dimension. For example, annotations for a listing ID could be listing_title or listing_quantity_sold."
+ },
+ "DimensionMetadata": {
+ "type": "object",
+ "properties": {
+ "dataType": {
+ "type": "string",
+ "description": "The data type of the dimension value used to create the report. For implementation help, refer to eBay API documentation"
+ },
+ "dimensionKey": {
+ "type": "string",
+ "description": "The name of the dimension used to create the report."
+ },
+ "dimensionKeyAnnotations": {
+ "type": "array",
+ "description": "An list of annotation keys associated with the specified dimension of the report.",
+ "items": {
+ "$ref": "#/components/schemas/DimensionKeyAnnotation"
+ }
+ }
+ },
+ "description": "This type defines the dimension used to create the report and the annotation keys associated with that dimension."
+ },
+ "DiscountBenefit": {
+ "type": "object",
+ "properties": {
+ "amountOffItem": {
+ "description": "The monetary amount that is discounted off an item (or items) when the discount criteria is met.
For threshold discounts, where the buyer triggers the discount, the valid values for this field are:
5, 6, 7, 8, 9, 10, 15, 20, 25,
30, 35, 40, 45, 50, 55, 60, 65,
70, 75, 80, 85, 90, 95, 100, 110,
120, 125, 150, 200, 250
For markdown discounts, the range is greater, as outlined below and detailed more precisely here: - $1 increments from $5 to $100
- $5 increments from $105 to $1,000
- $100 increments from $1,100 to $15,000
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "amountOffOrder": {
+ "description": "Used for threshold discounts, this is the monetary amount that is discounted off an order when the discount criteria is met. Because this field is valid only for orders, it's not a valid combination to use with markdown discounts.
Valid values for the associated amountOffOrder.value field:
5, 6, 7, 8, 9, 10, 15, 20, 25,
30, 35, 40, 45, 50, 55, 60, 65,
70, 75, 80, 85, 90, 95, 100, 110,
120, 125, 150, 200, 250",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "percentageOffItem": {
+ "type": "string",
+ "description": "The percentage applied to the sales price that is discounted off the discounted item (or items) when the discount criteria is met.
Valid integer values for percentage off: Min: 5 Max: 80"
+ },
+ "percentageOffOrder": {
+ "type": "string",
+ "description": "Used for threshold discounts, this is the percentage of the order price that is discounted off the order when the discount criteria is met. This field is not value for markdown discounts.
Valid integer values for ORDER_DISCOUNT discounts: Min: 5 Max: 80
For VOLUME_DISCOUNT discounts: Must be set to 0 for the first discount rule."
+ }
+ },
+ "description": "This container defines the discount as either a monetary amount or a percentage of the sales price. Important!: You must populate one and only one of the fields in this container:
- amountOffItem
- amountOffOrder
- percentageOffItem
- percentageOffOrder
Tip: Refer to Configuring discounts for threshold discounts for information and examples on how to combine discountBenefit and discountSpecification values to create different types of discounts.
"
+ },
+ "DiscountRule": {
+ "type": "object",
+ "properties": {
+ "discountBenefit": {
+ "description": "This container defines the discount as either a monetary amount or a percentage of the sales price. Note: When configuring discount benefits, populate just one of the following fields in the discountBenefit container:
- amountOffItem
- amountOffOrder
- percentageOffItem
- percentageOffOrder
For volume pricing, only percentageOffOrder is applicable as a discountBenefit. Also, the first discountBenefit container in a volume pricing configuration must set percentageOffOrder to 0.
Tip: Refer to Configuring threshold discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of discounts.
",
+ "$ref": "#/components/schemas/DiscountBenefit"
+ },
+ "discountSpecification": {
+ "description": "This container defines the criteria for when the discounts trigger, such as the minimum quantity that the buyer must purchase before the discount kicks in. The discount is applied each time the criteria defined by this container is met. When configuring the rules that govern when the discounts are applied, populate just one of the following fields in the discountSpecification container:
- minAmount
- minQuantity
- forEachQuantity
- forEachAmount
Important: When configuring volume pricing discounts, only minQuantity is applicable as a discountSpecification. Also, the configuration for minQuantity in a volume pricing configuration is specific. In the first discountSpecification container, set minQuantity to 1, and in the second, set minQuantity to 2. If you include a third discountRules pair, minQuantity must be set to 3, and in a fourth, it must be set to 4. Also, you must set a ruleOrder value in each discountRules container. In the first container, discountRules must be set to 1, and in each subsequent container, the value be be incremented by 1. For more, see Configuring volume pricing discounts.
Tip: see Configuring threshold discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of discounts.
",
+ "$ref": "#/components/schemas/DiscountSpecification"
+ },
+ "maxDiscountAmount": {
+ "description": "The limit on how much a buyer can save using a CODED_COUPON discount type. Permitted values are 1-1000. Supported currency codes include USD, GBP, EUR, and AUD. Note: The Currency Code for 'maxDiscountAmount' must be the same as the Currency Code for 'budget'.
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "ruleOrder": {
+ "type": "integer",
+ "description": "This field indicates the order in which the discountRules are presented. The value specified for this field must equal the associated minQuantity value.
Required if you are creating a volume pricing discount.",
+ "format": "int32"
+ }
+ },
+ "description": "This complex type defines a discount as being either a monetary amount or a percentage of a sales price that's subtracted from the price of an item or order. Set the amount of the discount and the rules that govern when the discount triggers using the discountBenefit and discountSpecification fields.
Note: In volume pricing discounts, you must configure at least two discountRule containers and at most four.
"
+ },
+ "DiscountSpecification": {
+ "type": "object",
+ "properties": {
+ "forEachAmount": {
+ "description": "The monetary amount that must be spent on discounted items before the discount is applied.
Valid values for the associated forEachAmount.value field:
5, 10, 15, 20, 25, 30, 35, 40, 45, 49,
50, 55, 59, 60, 65, 69, 70, 75, 79, 80,
85, 89, 90, 95, 99, 100, 110, 120, 125,
149, 150, 175, 199, 200, 249, 250, 299,
300, 350, 399, 400, 450, 499, 500",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "forEachQuantity": {
+ "type": "integer",
+ "description": "The number of items that must be purchased in order to qualify for the discount.
Valid values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
12, 13, 14, 15, 16, 17, 18, 19
20, 25, 50, 75, 100",
+ "format": "int32"
+ },
+ "minAmount": {
+ "description": "Known as the \"threshold amount\", the minimum dollar amount that needs to be spent on discounted items in order to qualify for the discount.
Valid values for the associated minAmount.value field:
5, 10, 15, 20, 25, 30, 35, 40, 45, 49,
50, 55, 59, 60, 65, 69, 70, 75, 79, 80,
85, 89, 90, 95, 99, 100, 110, 120,
125, 149, 150, 175, 199, 200, 249, 250, 299,
300, 350, 399, 400, 450, 499, 500",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "minQuantity": {
+ "type": "integer",
+ "description": "The minimum quantity of discounted items that needs to be bought in order to qualify for the discount.
Valid values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
12, 13, 14, 15, 16, 17, 18, 19
20, 25, 50, 75, 100",
+ "format": "int32"
+ },
+ "numberOfDiscountedItems": {
+ "type": "integer",
+ "description": "Use this field to configure \"Buy One Get One\" (or BOGO) discounts.
You must couple this field with forEachQuantity and an amountOffItem or percentOffItem field to configure your BOGO discount. This field is not valid with order-based discounts.
The value of this field represents the number of items to be discounted when other discount criteria is met. For example, when the buyer adds the number of items identified by the forEachQuantity value to their cart, they are then eligible to receive the stated discount from an additional number of like items (the number of which is identified by this field) when they add those items to their cart. To receive the discount, the buyer must purchase the number of items indicated by forEachQuantity plus the number indicated by this field.
Valid values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10",
+ "format": "int32"
+ }
+ },
+ "description": "This container defines the criteria for when the discounts trigger, such as the minimum quantity the buyer must purchase before the discount kicks in. The discount is applied each time the criteria defined by this container is met. Note: When configuring the rules that govern when the discounts are applied, populate just one of the following fields in the discountSpecification container:
- minAmount
- minQuantity
- forEachQuantity
- forEachAmount
Tip: Refer to Configuring threshold discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of discounts.
"
+ },
+ "DynamicAdRatePreference": {
+ "type": "object",
+ "properties": {
+ "adRateAdjustmentPercent": {
+ "type": "string",
+ "description": "The percentage above or below (-) the eBay suggested ad rate that a seller is willing to pay.
This specifies the maximum and minimum values to which an ad rate can be dynamically adjusted."
+ },
+ "adRateCapPercent": {
+ "type": "string",
+ "description": "The maximum value (specified as a percentage) to which the eBay suggested ad rate can be adjusted. The adjusted ad rate will never exceed this percentage."
+ }
+ },
+ "description": "A type that defines the ad rate details for a general strategy ad campaign."
+ },
+ "Error": {
+ "type": "object",
+ "properties": {
+ "category": {
+ "type": "string",
+ "description": "The category type for this error or warning. It takes an ErrorCategory object which can have one of three values:Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as \"Seller does not ship item to Antarctica\" or \"Buyer ineligible to purchase an alcoholic item\". Business errors are not syntactical input errors.Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.
"
+ },
+ "domain": {
+ "type": "string",
+ "description": "Name of the domain containing the service or application."
+ },
+ "errorId": {
+ "type": "integer",
+ "description": "A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.",
+ "format": "int32"
+ },
+ "inputRefIds": {
+ "type": "array",
+ "description": "Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "longMessage": {
+ "type": "string",
+ "description": "An expanded version of message that should be around 100-200 characters long, but is not required to be such."
+ },
+ "message": {
+ "type": "string",
+ "description": "An end user and app developer friendly device agnostic message. It explains what the error or warning is, and how to fix it (in a general sense). Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale."
+ },
+ "outputRefIds": {
+ "type": "array",
+ "description": "Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "parameters": {
+ "type": "array",
+ "description": "This optional complex field type contains a list of one or more context-specific ErrorParameter objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.",
+ "items": {
+ "$ref": "#/components/schemas/ErrorParameter"
+ }
+ },
+ "subdomain": {
+ "type": "string",
+ "description": "Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain."
+ }
+ },
+ "description": "A container that defines the elements of error and warning messages."
+ },
+ "ErrorParameter": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "Name of the entity that threw the error."
+ },
+ "value": {
+ "type": "string",
+ "description": "A description of the error."
+ }
+ },
+ "description": "Container for a error parameter."
+ },
+ "FundingStrategy": {
+ "type": "object",
+ "properties": {
+ "adRateStrategy": {
+ "type": "string",
+ "description": "This field is used to set the ad rate strategy for a Cost Per Sale (CPS) campaign.
The default value for this field is FIXED. If this field is omitted, the default value will be used.
Note: This field is not applicable for Cost Per Click (CPC) or offsite campaigns. For implementation help, refer to eBay API documentation"
+ },
+ "biddingStrategy": {
+ "type": "string",
+ "description": "Indicates the bidding strategy for an onsite Cost Per Click (CPC) campaign that uses manual targeting.
Note: This field is not applicable for smart targeting campaigns.
Valid values are:FIXED
When using a fixed bidding strategy, sellers manually assign and adjust keyword bids for the CPC campaign.DYNAMIC
When using a dynamic bidding strategy, eBay manages the campaign's keyword bids and automatically updates them daily to the suggested bid.
Note: For a CPC campaign using dynamic bidding, sellers can continue to manually add keywords for the campaign, but they are no longer able to manually adjust their associated bid values. In order to manually adjust bid values, sellers must use the FIXED bidding strategy.
Default value: FIXED For implementation help, refer to eBay API documentation"
+ },
+ "bidPercentage": {
+ "type": "string",
+ "description": "The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
This is the default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.
Note:This field is only relevant for campaigns that use the CPS funding model and a fixed ad rate. It is not used for campaigns that use the Cost Per Click (CPC) funding model and should not be provided when the selected adRateStrategy for the campaign is dynamic.
Note: This field has a minimum value of 2.0 and a maximum value of 100.0."
+ },
+ "bidPreferences": {
+ "type": "array",
+ "description": "This container indicates the bidding preferences of the campaign, such as the maximum CPC amount.
Note: This container is only applicable for smart targeting campaigns.
This container is required if the user wants to create a Smart Targeting campaign.",
+ "items": {
+ "$ref": "#/components/schemas/BidPreference"
+ }
+ },
+ "dynamicAdRatePreferences": {
+ "type": "array",
+ "description": "A field that indicates whether a single, user-defined bid percentage (also known as the ad rate) should be used, or whether eBay should automatically adjust listings to maintain the daily suggested bid percentage.
Note: Dynamic adjustment is only applicable when the adRateStrategy is set to DYNAMIC This field is not applicable for offsite campaigns.
Default: FIXED",
+ "items": {
+ "$ref": "#/components/schemas/DynamicAdRatePreference"
+ }
+ },
+ "fundingModel": {
+ "type": "string",
+ "description": "Indicates the model that eBay uses to calculate the Promoted Listings fee. For a description of the funding model types, refer to FundingModelTypeEnum. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type defines how the Promoted Listings fee is calculated for a Promoted Listings ad campaign."
+ },
+ "GetEmailCampaignAudiencesResponse": {
+ "type": "object",
+ "properties": {
+ "audiences": {
+ "type": "array",
+ "description": "An array of audiences available for the specified email campaign type. If no audiences are available, the result will return an empty array.",
+ "items": {
+ "$ref": "#/components/schemas/CampaignAudience"
+ }
+ },
+ "href": {
+ "type": "string",
+ "description": "The URL to the current page of store email campaign audiences."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The value of the limit parameter submitted in the request, which is the maximum number of store email campaign audiences to return on a page from the result set.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "This value indicates the offset used for the current page of store email campaign audiences returned.",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The URI for the previous page of results. This is returned if there is a previous page of results from the result set."
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of available audiences returned under the query conditions.",
+ "format": "int32"
+ }
}
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/setup_quick_campaign": {
- "post": {
- "tags": [
- "campaign"
- ],
- "description": "This method allows the seller to expedite the creation of a Promoted Listings Advanced (PLA) campaign.
Sellers only need to provide basic campaign information, such as the user-defined campaign name, the start date (and optionally the end date) of the campaign, the daily budget amount of the campaign, and the eBay marketplace where the campaign will be hosted. The seller must also identify the items they want to place in the campaign by adding the listing id of each item in the listingIds array of the request.
Using the provided listingIds, eBay creates ad groups for the campaign and organizes the listings into the appropriate ad group. eBay then adds keywords to each ad group and assigns each keyword a suggested bid.
Campaigns created using this method will be in DRAFT status upon creation.
The location response header returned contains the getCampaign URI to retrieve the newly created campaign that is in draft status. Sellers should make this call to review and approve the campaign before they use the launchCampaign method to start the campaign.
Note: Promoted Listing Standard (PLS) campaigns are not supported. ",
- "operationId": "setupQuickCampaign",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This type defines the fields to create a quick setup Promoted Listings Advanced (PLA) campaign.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the fields to create a quick setup Promoted Listings Advanced (PLA) campaign.",
- "$ref": "#/components/schemas/QuickSetupRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "201": {
- "description": "Created",
- "headers": {
- "Location": {
- "schema": {
- "type": "string",
- "description": "The location response header contains the getCampaign URI to the newly created quick setup campaign. The URL includes the eBay-assigned campaignId, which you can use to reference the campaign."
+ },
+ "GetEmailCampaignResponse": {
+ "type": "object",
+ "properties": {
+ "audiences": {
+ "type": "array",
+ "description": "An array of one or more audiences associated with the email campaign.",
+ "items": {
+ "$ref": "#/components/schemas/CampaignAudience"
+ }
+ },
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of an eBay category or an eBay store category. This field is returned if a seller has applied the email campaign to a specific category.
The categoryType value will indicate if the category ID is for an eBay category or an eBay store category."
+ },
+ "categoryType": {
+ "type": "string",
+ "description": "The enumeration value returned here indicates if the categoryId value is the identifier of an eBay category or an eBay store category.
This field is returned if a seller has applied the email campaign to a specific category. For implementation help, refer to eBay API documentation"
+ },
+ "creationDate": {
+ "type": "string",
+ "description": "The date and time that the email campaign was created, given in UTC format."
+ },
+ "emailCampaignId": {
+ "type": "string",
+ "description": "The unique identifier of the email campaign."
+ },
+ "emailCampaignStatus": {
+ "type": "string",
+ "description": "The email campaign status. See EmailCampaignStatusEnum for a list of valid statuses. For implementation help, refer to eBay API documentation"
+ },
+ "emailCampaignType": {
+ "type": "string",
+ "description": "The email campaign type. See CampaignTypeEnum for valid email campaign types. For implementation help, refer to eBay API documentation"
+ },
+ "itemIds": {
+ "type": "array",
+ "description": "The listing IDs of the items that were manually added to the email campaign.
Only listings added manually by the seller are returned. Returns a null array if no listings were added.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "itemSelectMode": {
+ "type": "string",
+ "description": "The mode used to select the items listed in the email campaign. For implementation help, refer to eBay API documentation"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The eBay marketplace where the email campaign is active. See MarketplaceIdEnum for a list of marketplace IDs."
+ },
+ "modificationDate": {
+ "type": "string",
+ "description": "The date and time the email campaign was last modified, given in UTC format."
+ },
+ "personalizedMessage": {
+ "type": "string",
+ "description": "The body of the email campaign sent to the audience."
+ },
+ "priceRange": {
+ "description": "The price range and currency set within the email campaign. This container will only return if a price range was set.",
+ "$ref": "#/components/schemas/PriceRange"
+ },
+ "promotionId": {
+ "type": "string",
+ "description": "The ID of the discount that was assigned to the email campaign."
+ },
+ "promotionSelectMode": {
+ "type": "string",
+ "description": "Indicates whether the listings that the discount was applied to were selected manually or automatically.
This field will only return if a discount was applied. For implementation help, refer to eBay API documentation"
+ },
+ "scheduleDate": {
+ "type": "string",
+ "description": "The date and time that the email campaign newsletter is scheduled to send, given in UTC format. This field is only returned if the seller set the start of the email campaign to a date in the future."
+ },
+ "scheduleDateType": {
+ "type": "string",
+ "description": "The schedule type of the email campaign. See ScheduleDateTypeEnum. For implementation help, refer to eBay API documentation"
+ },
+ "sentDate": {
+ "type": "string",
+ "description": "The date and time that the email campaign was sent, given in UTC format."
+ },
+ "sort": {
+ "type": "string",
+ "description": "The sort rule is used to display the items in the email campaign. If no sort rule was selected, the default will be NEWLY_LISTED. For implementation help, refer to eBay API documentation"
+ },
+ "subject": {
+ "type": "string",
+ "description": "The email campaign subject."
+ }
}
- }
},
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
+ "GetEmailCampaignsResponse": {
+ "type": "object",
+ "properties": {
+ "campaigns": {
+ "type": "array",
+ "description": "A list of email campaigns that match the search criteria.",
+ "items": {
+ "$ref": "#/components/schemas/CampaignDTO"
+ }
+ },
+ "href": {
+ "type": "string",
+ "description": "The URL to the current page of store email campaigns."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The value of the limit parameter submitted in the request, which is the maximum number of store email campaigns to return on a page from the result set.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "This value indicates the offset used for current page of store email campaigns being returned.",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The URI for the previous page of results. This is returned if there is a previous page of results from the result set."
+ },
+ "total": {
+ "type": "integer",
+ "description": "Total number of available results returned under the filter criteria submitted in the request.",
+ "format": "int32"
+ }
}
- }
- },
- "x-response-codes": {
- "errors": {
- "36362": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "Quick setup is unavailable for the {count} of the selected listings."
- },
- "36365": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category is not supported by the Promoted Listing service for multi-quantity listings."
- },
- "36366": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing id was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace."
- },
- "36367": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing id does not belong to the seller making this call."
- },
- "36368": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing id is not a fixed price item. This is a requirement for a promoted listing."
- },
- "36369": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing id is invalid or has ended."
+ },
+ "GetEmailPreviewResponse": {
+ "type": "object",
+ "properties": {
+ "content": {
+ "type": "string",
+ "description": "The raw HTML code of the email campaign contents. The client side can use this HTML output directly.
Because the contents of an email campaign are subject to change, these contents are a \"snapshot\" of the email campaign at a specific time and date, indicated by the renderDate field."
+ },
+ "renderDate": {
+ "type": "string",
+ "description": "The date and time when a \"snapshot\" of the email campaign contents contained in the content result was taken. Given in UTC format."
+ }
}
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35006": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'fundingStrategy' is required for this call."
- },
- "35014": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing Id is required for this call."
- },
- "35017": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'currency' is not valid or missing."
- },
- "35019": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Campaign name is required for this call."
- },
- "35020": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
- },
- "35021": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign with the name of {campaignName} already exists. Please provide a different name."
- },
- "35023": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
- },
- "35024": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign start date {startDate} cannot be after the end date {endDate}."
- },
- "35025": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign start date is required."
- },
- "35026": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign start or end date {date} cannot be in the past."
- },
- "35037": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing associated with listing Id {listingId} has ended."
- },
- "35038": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The funding model is required. Valid values for 'fundingModel' are: {fundingModelValues}."
- },
- "35041": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'marketplaceId' is required."
- },
- "36160": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This functionality is only supported for CPC funding model."
+ },
+ "GetEmailReportResponse": {
+ "type": "object",
+ "properties": {
+ "clickCount": {
+ "type": "integer",
+ "description": "The number of item listing links clicked from the body of campaign emails for the time range specified by the query.",
+ "format": "int32"
+ },
+ "openCount": {
+ "type": "integer",
+ "description": "The total email opened count for all email campaigns from a seller for the time range specified by the query.",
+ "format": "int32"
+ },
+ "totalSales": {
+ "description": "A seller's total sale amount for the time range specified by the query.",
+ "$ref": "#/components/schemas/Amount"
+ }
}
- }
- }
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35051": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}."
- },
- "35052": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
- },
- "35054": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing Id {listingId} was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace."
- },
- "35057": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing Id {listingId} does not belong to the seller making this call."
- },
- "35058": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The listing Id {listingId} is not a fixed price item. This is a requirement for a promoted listing."
- },
- "36152": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'bidPercentage' is not supported for CPC funding model."
- },
- "36153": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget currency {currency} is not supported for {fieldName}. The supported currency for the {marketplaceId} marketplace is {supportedCurrencyCode}."
- },
- "36154": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget below minimum allowed {minAllowed}."
- },
- "36155": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget above maximum allowed {maxAllowed}."
- },
- "36157": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget is required for campaigns with CPC funding model."
- },
- "36158": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget value format {dailyBudgetValue} cannot have more than 2 decimal places."
- },
- "36159": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'marketplaceId' {marketPlaceId} is not supported. Promoted Listings with CPC funding model is supported only on these marketplaces: {supportedMarketplaces}."
- },
- "36363": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "Quick setup is unavailable for the selected listings. Please check the listings and submit the call again."
+ },
+ "InventoryCriterion": {
+ "type": "object",
+ "properties": {
+ "inventoryCriterionType": {
+ "type": "string",
+ "description": "Indicates how the items to be discounted are selected. You can include inventory by ID, using rules, or globally include all your inventory. For implementation help, refer to eBay API documentation"
+ },
+ "inventoryItems": {
+ "type": "array",
+ "description": "An array of containers for the seller's inventory reference IDs (also known as an \"SKU\" or \"custom label\") to be added to the discount.
Note: The request can have either inventoryItems or listingIds, but not both.
Maximum: 2000 parent items
Maximum SKU or custom label length: 50 characters
Required if InventoryCriterionType is set to INVENTORY_BY_VALUE, you must specify either inventoryItems or listingIds.",
+ "items": {
+ "$ref": "#/components/schemas/InventoryItem"
+ }
+ },
+ "listingIds": {
+ "type": "array",
+ "description": "An array of eBay listing IDs to be discounted.
Note: The request can have either inventoryItems or listingIds, but not both.
Required: All listings being discounted must offer an electronic payment method.
Maximum: 2000 parent items
Maximum SKU or custom label length: 50 characters
Required if InventoryCriterionType is set to INVENTORY_BY_VALUE, you must specify either inventoryItems or listingIds.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "ruleCriteria": {
+ "description": "This container defines a set of inventory selection rules for a discount.
When defining rule criteria, you must limit item exclusions to 100 IDs when you choose from live inventory.
Required if InventoryCriterionEnum is set to INVENTORY_BY_RULE or INVENTORY_ANY.",
+ "$ref": "#/components/schemas/RuleCriteria"
+ }
+ },
+ "description": "This type defines either the selections rules or the list of listing IDs for the discount. The \"listing IDs\" are are either the seller's item IDs or the eBay listing IDs."
+ },
+ "InventoryItem": {
+ "type": "object",
+ "properties": {
+ "inventoryReferenceId": {
+ "type": "string",
+ "description": "The unique identifier of a single-item listing or a multi-variation listing.
To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify and item ID or a SKU (if the SKU is defined in the listing)
To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API."
+ }
+ },
+ "description": "This type defines the fields for the seller inventory reference IDs (also known as an \"SKU\" or \"custom label\")."
+ },
+ "InventoryReference": {
+ "type": "object",
+ "properties": {
+ "inventoryReferenceId": {
+ "type": "string",
+ "description": "The unique identifier of a single-item listing or a multi-variation listing.
To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).
To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API.
Required if if you supply an inventoryReferenceType."
+ },
+ "inventoryReferenceType": {
+ "type": "string",
+ "description": "Indicates the type of item indicated by the inventoryReferenceId.
This value can be set to either INVENTORY_ITEM or INVENTORY_ITEM_GROUP.
Required if if you supply an inventoryReferenceId. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This complex type is used to identify an item that is managed by the Inventory API. The type defines the fields contained in an inventory reference ID."
+ },
+ "ItemBasis": {
+ "type": "object",
+ "properties": {
+ "estimatedValue": {
+ "type": "integer",
+ "description": "The estimated value of the search impressions for items based on the provided dimensions.
Duration: 17 days
Total slots: 200
Channel: Dweb, Mweb, Native",
+ "format": "int32"
+ },
+ "metric": {
+ "type": "string",
+ "description": "The basis of the statistics. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A container for details regarding the basis for an item."
+ },
+ "ItemMarkdownStatus": {
+ "type": "object",
+ "properties": {
+ "listingMarkdownStatus": {
+ "type": "string",
+ "description": "Indicates the state assigned to the markdown discount using one of the status values. For implementation help, refer to eBay API documentation"
+ },
+ "statusChangedDate": {
+ "type": "string",
+ "description": "Identifies the date the last time the state of the discount changed. Both both markdown and markup events can trigger a status change."
+ },
+ "statusMessage": {
+ "type": "string",
+ "description": "An eBay-assigned text string that describes the status of the discount."
+ }
+ },
+ "description": "This type defines the status of a markdown discount."
+ },
+ "ItemPriceMarkdown": {
+ "type": "object",
+ "properties": {
+ "applyFreeShipping": {
+ "type": "boolean",
+ "description": "If set to true, free shipping is applied to the first shipping service specified for the item. The first domestic shipping option is set to \"free shipping,\" regardless if the shipping optionType for that service is set to FLAT_RATE, CALCULATED, or NOT_SPECIFIED (freight). This flag essentially adds free shipping as a part of the discount.
Default: false"
+ },
+ "autoSelectFutureInventory": {
+ "type": "boolean",
+ "description": "If set to true, eBay will automatically add inventory items to the markdown discount if they meet the selectedInventoryDiscounts criteria specified for the markdown discount.
Default: false"
+ },
+ "blockPriceIncreaseInItemRevision": {
+ "type": "boolean",
+ "description": "If set to true, price increases (including removing the free shipping flag) are blocked and an error message is returned if a seller attempts to adjust the price of an item that's partaking in this markdown discount. If set to false, an item is dropped from the markdown discount if the seller adjusts the price.
Default: false"
+ },
+ "description": {
+ "type": "string",
+ "description": "This field is required if you are configuring an MARKDOWN_SALE discount.
This is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\" A tag line appears under the \"offer-type text\" that is generated for the discount. The text is displayed on the offer tile that is shown on the seller's All Offers page and on the event page for the discount. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. This text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"20% off\".
Maximum length: 50"
+ },
+ "endDate": {
+ "type": "string",
+ "description": "The date and time the discount ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). The value supplied for endDate must be at least 24 hours after the value supplied for the startDate of the markdown discount.
For display purposes, convert this time into the local time of the seller.
Max value:14 days for the AT, CH, DE, ES, FR, IE, IT, and UK, marketplaces.45 days for all other marketplaces.
"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The eBay marketplace ID of the site where the markdown discount is hosted. Markdown discounts are supported on all eBay marketplaces. For implementation help, refer to eBay API documentation"
+ },
+ "name": {
+ "type": "string",
+ "description": "The seller-defined name or 'title' of the discount that the seller can use to identify a discount. This label is not displayed in end-user flows.
Maximum length: 90"
+ },
+ "priority": {
+ "type": "string",
+ "description": "This field is ignored in markdown discounts. For implementation help, refer to eBay API documentation"
+ },
+ "promotionImageUrl": {
+ "type": "string",
+ "description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT discounts, populate this field with a URL that points to an image to be used with the discount. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
+ },
+ "promotionStatus": {
+ "type": "string",
+ "description": "The current status of the discount. When creating a new discount, you must set this value to either DRAFT or SCHEDULED.
Note that you must set this value to SCHEDULED when you update a RUNNING discount. For implementation help, refer to eBay API documentation"
+ },
+ "selectedInventoryDiscounts": {
+ "type": "array",
+ "description": "A list that defines the sets of selected items for the markdown discount.",
+ "items": {
+ "$ref": "#/components/schemas/SelectedInventoryDiscount"
+ }
+ },
+ "startDate": {
+ "type": "string",
+ "description": "The date and time the discount starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
+ }
+ },
+ "description": "This type defines the fields used to describe an item price markdown discount."
+ },
+ "ItemPromotion": {
+ "type": "object",
+ "properties": {
+ "applyDiscountToSingleItemOnly": {
+ "type": "boolean",
+ "description": "This flag is relevant in only when promotionType is set to VOLUME_DISCOUNT. For details on volume pricing discounts, see Configuring volume pricing discounts.
If set to true, the discount is applied only when the buyer purchases multiple quantities of a single item that is being discounted. Otherwise, the discount applies to multiple quantities of any the items being discounted. Different variations of a multi-variation item are considered to be the same item. Note that this flag is not relevant if the inventoryCriterion container identifies a single listing ID for the discount."
+ },
+ "budget": {
+ "description": "This sets the budget for the CODED_COUPON discount type. Supported values range from 100-1000000. Supported currency codes include USD, GBP, EUR, and AUD. Note: The budget value for an active or paused discount can not be decreased.
Note: The Currency Code for 'budget' must be the same as the Currency Code for 'maxDiscountAmount'.
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "couponConfiguration": {
+ "description": "The configuration of a coded coupon discount.",
+ "$ref": "#/components/schemas/CouponConfiguration"
+ },
+ "description": {
+ "type": "string",
+ "description": "This is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\"
The tag line appears under the \"offer-type text\" that is generated for the discount and is displayed on the offer tile that's shown on the seller's All Offers page, and on the event page for the discount. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. The offer-type text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"Extra 20% off when you buy 3+\".
Maximum length: 50
Required if you are configuring CODED_COUPON, ORDER_DISCOUNT, or MARKDOWN_SALE discounts (and not valid for VOLUME_DISCOUNT discounts)."
+ },
+ "discountRules": {
+ "type": "array",
+ "description": "This container defines a discount using the following two required fields: - discountBenefit – Defines a discount as either a monetary amount or a percentage that is subtracted from the sales price of an item, a set of items, or an order.
- discountSpecification – Defines a set of rules that determine when the discount is applied.
Note: For volume pricing, you must specify at least two and not more than four discountBenefit/discountSpecification pairs. In addition, you must define each set of rules with a ruleOrder value that corresponds with the order of volume discounts you present.
Tip: Refer to Specifying item discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of discounts.
",
+ "items": {
+ "$ref": "#/components/schemas/DiscountRule"
+ }
+ },
+ "endDate": {
+ "type": "string",
+ "description": "The date and time the discount ends in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
+ },
+ "inventoryCriterion": {
+ "description": "A container that defines either the listing IDs or the selection rules that specify the items to be discounted. Listing IDs can be either eBay listing IDs or a list of the seller's inventory reference IDs (know as SKUs or custom labels). See the selectionRules container for the rule criteria you can use to select inventory. Note: All listings in Discounts Manager discounts must support an electronic payment method.
",
+ "$ref": "#/components/schemas/InventoryCriterion"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The eBay marketplace ID of the site where the threshold discount is hosted. Threshold discounts are currently supported on a limited number of eBay marketplaces. Valid values:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
For implementation help, refer to eBay API documentation"
+ },
+ "name": {
+ "type": "string",
+ "description": "The seller-defined name or \"title\" of the discount that the seller can use to identify a discounts. This label is not displayed in end-user flows.
Maximum length: 90"
+ },
+ "priority": {
+ "type": "string",
+ "description": "Applicable for only ORDER_DISCOUNT discounts, this field indicates the precedence of the discounts, which is used to determine the position of a discount on the seller's All Offers page. If an item is associated with multiple discounts, the discount with the higher priority takes precedence. For implementation help, refer to eBay API documentation"
+ },
+ "promotionImageUrl": {
+ "type": "string",
+ "description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT discounts, and not valid for VOLUME_DISCOUNT discounts.
Populate this field with a URL that points to an image to be used with the discount. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
+ },
+ "promotionStatus": {
+ "type": "string",
+ "description": "The current status of the discount. When creating a new discount, this value must be set to either DRAFT or SCHEDULED.
Note that you must set this value to SCHEDULED when you update a RUNNING discount. For implementation help, refer to eBay API documentation"
+ },
+ "promotionType": {
+ "type": "string",
+ "description": "Use this field to specify the type of the discount you are creating. The supported types are:
CODED_COUPON – A coupon code discount set with createItemPromotion.MARKDOWN_SALE – A markdown discount set with createItemPriceMarkdownPromotion.ORDER_DISCOUNT – A threshold discount set with createItemPromotion.VOLUME_DISCOUNT – A volume pricing discount set with createItemPromotion.
See the Discounts Manager documentation for details.
Required if you are creating a volume pricing discount (VOLUME_DISCOUNT).
For implementation help, refer to eBay API documentation"
+ },
+ "startDate": {
+ "type": "string",
+ "description": "The date and time the discount starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
+ }
+ },
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This type defines the fields that describe a threshold discount and includes the discount, the items being discounted, and the rules that specify when the discount is applied."
+ },
+ "ItemPromotionResponse": {
+ "type": "object",
+ "properties": {
+ "applyDiscountToSingleItemOnly": {
+ "type": "boolean",
+ "description": "If set to true, the discount is applied only when the buyer purchases multiple quantities of a single item being discounted. Otherwise, the discount applies to multiple quantities of any items being discounted. Different variations of a multi-variation item are considered to be the same item. Note that this flag is not relevant if the inventoryCriterion container identifies a single listing ID for the discount."
+ },
+ "budget": {
+ "description": "This sets the budget for the CODED_COUPON discount type. Supported values range from 100-1000000. Supported currency codes include USD, GBP, EUR, and AUD. Note: The budget value for an active or paused discount can not be decreased.
Note: The Currency Code for 'budget' must be the same as the Currency Code for 'maxDiscountAmount'.
",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "couponConfiguration": {
+ "description": "The configuration of a coded coupon discount.",
+ "$ref": "#/components/schemas/CouponConfiguration"
+ },
+ "description": {
+ "type": "string",
+ "description": "Required for CODED_COUPON discounts, this is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\" The tag line appears under the \"offer-type text\" that is generated for the discount and is displayed under the offer tile that is shown on the seller's All Offers page and on the event page for the discount. This tag line is not used with volume pricing discounts. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. This text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"Extra 20% off when you buy 3+\".
Maximum length: 50"
+ },
+ "discountRules": {
+ "type": "array",
+ "description": "A list containing the discount benefits (discountRule) and the rules that define when the benefit is applied (discountSpecification).",
+ "items": {
+ "$ref": "#/components/schemas/DiscountRule"
+ }
+ },
+ "endDate": {
+ "type": "string",
+ "description": "The date and time the discount ends in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
+ },
+ "inventoryCriterion": {
+ "description": "Returns either an array of listing IDs or the selection rules used to specify the items being discounted. Listing IDs can be either eBay listing IDs or an array of seller's inventory reference IDs (know as SKUs or custom labels). See the selectionRules container for the rule criteria you can use to select inventory.",
+ "$ref": "#/components/schemas/InventoryCriterion"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The eBay marketplace ID of the site where the threshold discount is hosted. Threshold discounts are currently supported on a limited number of eBay marketplaces. Valid values:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
For implementation help, refer to eBay API documentation"
+ },
+ "name": {
+ "type": "string",
+ "description": "The seller-defined name or \"title\" of the discount that the seller can use to identify a discount. This label is not displayed in end-user flows.
Maximum length: 90"
+ },
+ "priority": {
+ "type": "string",
+ "description": "Applicable for only ORDER_DISCOUNT discounts, this field indicates the precedence of the discount, which eBay uses to determine the position of a discount on the seller's All Offers page. If an item is associated with multiple discounts, the discount with the higher priority takes precedence. For implementation help, refer to eBay API documentation"
+ },
+ "promotionId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for the discount that's generated when the discount is created."
+ },
+ "promotionImageUrl": {
+ "type": "string",
+ "description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT discounts, and not applicable for VOLUME_DISCOUNT discounts, this field is a URL that points to an image for the discount. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
+ },
+ "promotionStatus": {
+ "type": "string",
+ "description": "The current status of the discount. When creating a new discount, this value must be set to either DRAFT or SCHEDULED. For implementation help, refer to eBay API documentation"
+ },
+ "promotionType": {
+ "type": "string",
+ "description": "Indicates the type of the discount, either CODED_COUPON, MARKDOWN_SALE, ORDER_DISCOUNT, or VOLUME_DISCOUNT. For implementation help, refer to eBay API documentation"
+ },
+ "startDate": {
+ "type": "string",
+ "description": "The date and time the discount starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
+ }
+ },
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This complex type defines the fields returned for an item (threshold) discount."
+ },
+ "ItemsPagedCollection": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the current page of results from the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
+ "format": "int32"
+ },
+ "listings": {
+ "type": "array",
+ "description": "An array of the listings associated with a discount.",
+ "items": {
+ "$ref": "#/components/schemas/ListingDetail"
+ }
+ },
+ "next": {
+ "type": "string",
+ "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
+ "format": "int32"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "A list of warnings that were generated by the request. Warning do not stop processing, but should be checked to ensure that the response contains the correct information.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type defines the fields for a paginated result set of discounts. The response consists of 0 or more sequenced pages that are returned from the complete result set, where each page consists of 0 or more items."
+ },
+ "Keyword": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "This field identifies the ad group that the keyword is associated with."
+ },
+ "bid": {
+ "description": "The bid associated with the keyword. This container will not be returned if the keyword does not have a defined bid value.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "keywordId": {
+ "type": "string",
+ "description": "The unique identifier of a keyword."
+ },
+ "keywordStatus": {
+ "type": "string",
+ "description": "The status of the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
+ },
+ "keywordText": {
+ "type": "string",
+ "description": "The text of the keyword."
+ },
+ "matchType": {
+ "type": "string",
+ "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A type that contains the details for keywords that are associated with an ad group.
Note: This type only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model."
+ },
+ "KeywordPagedCollectionResponse": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the current page of results from the result set."
+ },
+ "keywords": {
+ "type": "array",
+ "description": "This array contains all of the keywords that match the request criteria. Keywords will be sorted by adGroupId, regardless of whether you searched for keywords across the entire campaign, or if you searched for keywords within one or specific ad groups.",
+ "items": {
+ "$ref": "#/components/schemas/Keyword"
+ }
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The number of keywords returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results.
Max length: 2048"
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of keywords retrieved in the result set.
If no keywords are found, this field is returned with a value of 0.",
+ "format": "int32"
+ }
+ },
+ "description": "A type that defines the keywords of the paged collection."
+ },
+ "KeywordRequest": {
+ "type": "object",
+ "properties": {
+ "keywordText": {
+ "type": "string",
+ "description": "The text of the keyword. Keywords are not case sensitive and compound words can be used without additional encoding (for example, tennis ball).
You can use the getKeywords method to retrieve keyword values currently associated with the specified ad group.
Maximum number of characters: 100
Maximum number of words: 10 "
+ },
+ "matchType": {
+ "type": "string",
+ "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A type that defines the fields used by the Keyword method."
+ },
+ "KeywordResponse": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "The identifier of the ad group that the keyword was added to."
+ },
+ "errors": {
+ "type": "array",
+ "description": "This container will be returned if there is an issue creating the corresponding keyword and/or adding that keyword to the corresponding ad group.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "href": {
+ "type": "string",
+ "description": "The getKeyword URI for the keyword, which is used to retrieve the keyword. This URI will be returned for each successfully created keyword."
+ },
+ "keywordId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for a keyword that is generated for an ad group. This keyword ID will be generated for each successfully created keyword."
+ },
+ "keywordText": {
+ "type": "string",
+ "description": "The text of the keyword."
+ },
+ "matchType": {
+ "type": "string",
+ "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "An HTTP status code is returned for each keyword to indicate the success or failure of adding that keyword to the ad group.",
+ "format": "int32"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "List of warnings associated with this operation",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "A type that defines the response fields used by the Keyword method."
+ },
+ "ListingDetail": {
+ "type": "object",
+ "properties": {
+ "currentPrice": {
+ "description": "The container that returns the current price of the listing.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "freeShipping": {
+ "type": "boolean",
+ "description": "If set to true, the seller pays for the shipping (or that the item is marked for local pickup only) In this case, the listing does not have an associated shipping cost for the first listed domestic-shipping option (even if the first domestic-shipping option specifies a flat-rate or calculated shipping option). If false, the buyer is required to pay for a flat-rate or calculated cost shipping service."
+ },
+ "inventoryReferenceId": {
+ "type": "string",
+ "description": "The seller's inventory reference ID for a listing. Also known as the \"SKU\" or \"custom label,\" an inventory reference ID is either the ID of the listing or, if the listing has variations (such as a shirt that's available in multiple sizes and colors), the ID of the parent listing."
+ },
+ "inventoryReferenceType": {
+ "type": "string",
+ "description": "Indicates the type of the inventoryReferenceId, which can be either a single-SKU or a multi-SKU listing (INVENTORY_ITEM and INVENTORY_ITEM_GROUP, respectively).
Note: This value is not currently returned in the response."
+ },
+ "listingCategoryId": {
+ "type": "string",
+ "description": "The ID of the category that listing belongs to. The ID is a numeric and unique identifier for the category that is assigned by eBay."
+ },
+ "listingCondition": {
+ "type": "string",
+ "description": "An eBay-assigned value that indicates condition of the associated item. For more information, see Item condition ID and name values."
+ },
+ "listingConditionId": {
+ "type": "string",
+ "description": "The ID of the condition associated with the item. For more information, see Item condition ID and name values.
Note: This value is not currently returned in the response."
+ },
+ "listingId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID that is generated when the item is listed."
+ },
+ "listingPromotionStatuses": {
+ "type": "array",
+ "description": "A list of the status values assigned to the item and the date that each new status was assigned.",
+ "items": {
+ "$ref": "#/components/schemas/ItemMarkdownStatus"
+ }
+ },
+ "quantity": {
+ "type": "integer",
+ "description": "The number of items being sold in the listing.",
+ "format": "int32"
+ },
+ "storeCategoryId": {
+ "type": "string",
+ "description": "Store CategoryId (if any) that to which the listing belongs. This field is blank if there is no seller Store category ID."
+ },
+ "title": {
+ "type": "string",
+ "description": "The seller-defined title of the listing that a seller can use to identify the item. This label is not displayed in end-user flows."
+ }
+ },
+ "description": "This type defines the fields that describe a listing that is in a discount."
+ },
+ "MaxCpc": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "The allocated maximum CPC amount for a smart targeting campaign.
Both the currency and amount must be specified when allocating the Max CPC.",
+ "$ref": "#/components/schemas/Amount"
+ }
}
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
+ },
+ "MetricMetadata": {
+ "type": "object",
+ "properties": {
+ "dataType": {
+ "type": "string",
+ "description": "The data type of the returned metric value. For implementation help, refer to eBay API documentation"
+ },
+ "metricKey": {
+ "type": "string",
+ "description": "The name of the metric."
+ }
+ },
+ "description": "This type defines the name and data type of a metric."
+ },
+ "NegativeKeyword": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "An ad group ID that is generated when an ad group is first created and associated with a campaign.
Note: You can call the getAdGroups method to retrieve the ad group IDs for a seller."
+ },
+ "campaignId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created."
+ },
+ "negativeKeywordId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for a negative keyword. This keyword ID will be generated for each successfully created negative keyword."
+ },
+ "negativeKeywordMatchType": {
+ "type": "string",
+ "description": "A field that defines the match type for the negative keyword.
Note: Broad matching of negative keywords is not currently supported.
Valid Values: For implementation help, refer to eBay API documentation"
+ },
+ "negativeKeywordStatus": {
+ "type": "string",
+ "description": "A field that defines the status of the negative keyword. For implementation help, refer to eBay API documentation"
+ },
+ "negativeKeywordText": {
+ "type": "string",
+ "description": "The text for the negative keyword."
+ }
+ },
+ "description": "A type that defines the fields for a negative keyword."
+ },
+ "NegativeKeywordPagedCollectionResponse": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the current page of results from the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
+ "format": "int32"
+ },
+ "negativeKeywords": {
+ "type": "array",
+ "description": "A list of negative keywords returned in the paginated collection.",
+ "items": {
+ "$ref": "#/components/schemas/NegativeKeyword"
+ }
+ },
+ "next": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.
Default: 0
Note: The items in a paginated result set use a zero-based list, where the first item in the list has an offset of 0.",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results."
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of result sets in the paginated collection.",
+ "format": "int32"
+ }
+ },
+ "description": "A type that defines the negative keywords, returned in a paged collection."
+ },
+ "NegativeKeywordResponse": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "A unique identifier for an ad group that is generated when an ad group is first created and associated with a campaign."
+ },
+ "campaignId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created."
+ },
+ "errors": {
+ "type": "array",
+ "description": "This container will be returned if there is an issue creating the corresponding negative keyword.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "href": {
+ "type": "string",
+ "description": "The URI for the negative keyword, which is used to retrieve the negative keyword. This URI will be returned for each successfully created negative keyword."
+ },
+ "negativeKeywordId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for a negative keyword. This negative keyword ID will be generated for each successfully created negative keyword."
+ },
+ "negativeKeywordMatchType": {
+ "type": "string",
+ "description": "The match type for the negative keyword.
Note: Broad matching of negative keywords is not currently supported.
Valid Values: For implementation help, refer to eBay API documentation"
+ },
+ "negativeKeywordText": {
+ "type": "string",
+ "description": "The text for the negative keyword."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "The status of the request to create a negative keyword. This field indicates whether the process was successful or not.",
+ "format": "int32"
+ }
+ },
+ "description": "A type that defines the negative keyword response."
+ },
+ "PriceRange": {
+ "type": "object",
+ "properties": {
+ "currency": {
+ "type": "string",
+ "description": "Specifies the currency of the listings in an email campaign using one of the three-digit codes of the CurrencyCodeEnum type."
+ },
+ "gte": {
+ "type": "number",
+ "description": "The listings selected will be greater than or equal to this value. The value entered must be given in number format, such as 20.00.
Either gte, lte, or both must contain a value if the seller wishes to use a price range."
+ },
+ "lte": {
+ "type": "number",
+ "description": "The listings selected will be less than or equal to this value. The value entered must be given in number format, such as 100.00.
Either gte, lte, or both must contain a value if the seller wishes to use a price range."
+ }
+ },
+ "description": "The price range."
+ },
+ "PromotionDetail": {
+ "type": "object",
+ "properties": {
+ "couponCode": {
+ "type": "string",
+ "description": "A unique code that buyers can use during checkout to receive a discount. The code must be unique across eBay."
+ },
+ "description": {
+ "type": "string",
+ "description": "This is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\" Tag lines appear under the \"offer-type text\" that is generated for a discount and displayed under the offer tile that is shown on the seller's All Offers page and on the discount's event page. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. This text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"Extra 20% off when you buy 3+\".
Maximum length: 50
Required if you are configuring ORDER_DISCOUNT or MARKDOWN_SALE discoutns (and not valid for VOLUME_DISCOUNT discounts)."
+ },
+ "endDate": {
+ "type": "string",
+ "description": "The date and time the discount ends in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The eBay marketplace ID of the site where the discount is hosted. Threshold discounts are supported on a select set of marketplaces while markdown discounts are supported on all eBay marketplaces. Valid values for threshold discounts are as follows:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
For implementation help, refer to eBay API documentation"
+ },
+ "name": {
+ "type": "string",
+ "description": "The seller-defined name or \"title\" of the discount, such as \"Buy 1 Get 1\", that the seller can use to identify a discount. This label is not displayed in end-user flows.
Maximum length: 90"
+ },
+ "priority": {
+ "type": "string",
+ "description": "Applicable for only ORDER_DISCOUNT discount, this field indicates the precedence of the discount, which is used to determine the position of a discount on the seller's All Offers page. If an item is associated with multiple discounts, the discount with the higher priority takes precedence. For implementation help, refer to eBay API documentation"
+ },
+ "promotionHref": {
+ "type": "string",
+ "description": "The URI of the discount details."
+ },
+ "promotionId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for the discount that's generated when the discount is created."
+ },
+ "promotionImageUrl": {
+ "type": "string",
+ "description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT discount, and not applicable for VOLUME_DISCOUNT discounts, this field is a URL that points to an image for the discount. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
+ },
+ "promotionStatus": {
+ "type": "string",
+ "description": "The current status of the discount. When creating a new discount, you must set this value to either DRAFT or SCHEDULED. For implementation help, refer to eBay API documentation"
+ },
+ "promotionType": {
+ "type": "string",
+ "description": "Indicates type of the discount, either CODED_COUPON, MARKDOWN_SALE, ORDER_DISCOUNT, or VOLUME_DISCOUNT. For implementation help, refer to eBay API documentation"
+ },
+ "startDate": {
+ "type": "string",
+ "description": "The date and time the discount starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
+ }
+ },
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This type defines the fields that describe a discount. This includes all the information about a discount except for the listings that are a part of the discount."
+ },
+ "PromotionReportDetail": {
+ "type": "object",
+ "properties": {
+ "averageItemDiscount": {
+ "description": "The average item discount is the average discount that has been applied to each item being discounted. This value is calculated as follows:
totalDiscount / itemsSoldQuantity = averageItemDiscount",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "averageItemRevenue": {
+ "description": "The average item revenue is the average revenue that has been received for each item being discounted.. This value is calculated as follows:
totalSales / itemsSoldQuantity = averageItemRevenue",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "averageOrderDiscount": {
+ "description": "The average order discount is the average discount that has been applied to each order that has an active discount. This value is calculated as follows:
totalDiscount / numberOfOrdersSold = averageOrderDiscount",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "averageOrderRevenue": {
+ "description": "The average order revenue is the average revenue that has been received for each order that has an active discount. This value is calculated as follows:
totalSales / numberOfOrdersSold = averageOrderRevenue",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "averageOrderSize": {
+ "type": "string",
+ "description": "The average order size is the average number of items that each order contained that have an active discount. This value is calculated as follows:
itemsSoldQuantity / numberOfOrdersSold = averageOrderSize "
+ },
+ "baseSale": {
+ "description": "This is the monetary amount of items purchased that have been discounted where the threshold wasn't met, so the discount was not applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. One buyer purchased only one pair of socks, so they pay the full price of $5. Here, your baseSale amount would be $5.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "itemsSoldQuantity": {
+ "type": "integer",
+ "description": "This is the quantity of items purchased in a threshold discount where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your number of items sold (itemsSoldQuantity) would be 2 and you number of orders sold (numberOfOrdersSold) would be 1.",
+ "format": "int32"
+ },
+ "numberOfOrdersSold": {
+ "type": "integer",
+ "description": "This is the number of orders sold in a threshold discount where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your numberOfOrdersSold would be 1 and your itemsSoldQuantity would be 2.",
+ "format": "int32"
+ },
+ "percentageSalesLift": {
+ "type": "string",
+ "description": "The percentage sales lift is the total dollar amount gained due to discounts. This value is calculated as follows:
promotionSale / totalSale = percentageSalesLift "
+ },
+ "promotionHref": {
+ "type": "string",
+ "description": "The URI of the discount report."
+ },
+ "promotionId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for the discount that's generated when the discount is created."
+ },
+ "promotionReportId": {
+ "type": "string",
+ "description": "The unique eBay-assigned ID of the discount report that is generated when the report is created."
+ },
+ "promotionSale": {
+ "description": "This is the monetary amount of the items sold in a threshold discount where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your promotionSale amount would be $7.50.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "promotionType": {
+ "type": "string",
+ "description": "Indicates the type of the discount, either CODED_COUPON, MARKDOWN_SALE, ORDER_DISCOUNT, or VOLUME_DISCOUNT. For implementation help, refer to eBay API documentation"
+ },
+ "totalDiscount": {
+ "description": "This is the monetary discount amount applied to the sale of items in a threshold discount where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your totalDiscount amount would be $2.50.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "totalSale": {
+ "description": "This is the total monetary sales amount of all items sold that were discounted.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. You make one sale where the buyer purchases only one pair of socks and they pay the full price of $5 (baseSale). You make a second sale where the buyer purchases two pairs of socks and they pay $7.50, for both pairs (promotionSale). Your totalSale would be $12.50. This value is calculated as follows:
baseSale + promotionSale = totalSale",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This type defines the fields in a discount-level report."
+ },
+ "PromotionsPagedCollection": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the current page of results from the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
+ },
+ "promotions": {
+ "type": "array",
+ "description": "A list containing the details of each returned discount. This includes all the information about the discounts except for the listings that are discounted.",
+ "items": {
+ "$ref": "#/components/schemas/PromotionDetail"
+ }
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
+ "format": "int32"
+ }
+ },
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This type defines the fields in a paginated result set of seller discounts. The response consists of 0 or more sequenced pages that are returned from the complete result set, where each page consists of 0 or more items."
+ },
+ "PromotionsReportPagedCollection": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the current page of results from the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
+ },
+ "promotionReports": {
+ "type": "array",
+ "description": "A list of promotionReports contained in the paginated result set.",
+ "items": {
+ "$ref": "#/components/schemas/PromotionReportDetail"
+ }
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
+ "format": "int32"
+ }
+ },
+ "description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This type defines the fields in a paginated result set of discount-level reports. The response consists of 0 or more sequenced pages that are returned from the complete result set, where each page consists of 0 or more items."
+ },
+ "ProposedBid": {
+ "type": "object",
+ "properties": {
+ "currency": {
+ "type": "string",
+ "description": "The base currency applied to the value field to establish a monetary amount.
The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.
Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation"
+ },
+ "rangeEnd": {
+ "type": "string",
+ "description": "The end of the range specified for the bid."
+ },
+ "rangeStart": {
+ "type": "string",
+ "description": "The start of the range specified for the bid."
+ },
+ "value": {
+ "type": "string",
+ "description": "The value of the proposed bid."
+ }
+ },
+ "description": "A type that defines the data for a payment amount, such as the sale price."
+ },
+ "ReportMetadata": {
+ "type": "object",
+ "properties": {
+ "dimensionMetadata": {
+ "type": "array",
+ "description": "A list containing the metadata for the dimension used in the report.",
+ "items": {
+ "$ref": "#/components/schemas/DimensionMetadata"
+ }
+ },
+ "maxNumberOfDimensionsToRequest": {
+ "type": "integer",
+ "description": "The maximum number of dimensions that can be requested for the specified report type.",
+ "format": "int32"
+ },
+ "maxNumberOfMetricsToRequest": {
+ "type": "integer",
+ "description": "The maximum number of metrics that can be requested for the specified report type.",
+ "format": "int32"
+ },
+ "channel": {
+ "type": "string",
+ "description": "This field indicates whether a COST_PER_CLICK report type is related to an ON_SITE or OFF_SITE Promoted Listings campaign. This field is not returned for COST_PER_SALE report types since COST_PER_SALE campaigns are only available ON_SITE. For implementation help, refer to eBay API documentation"
+ },
+ "metricMetadata": {
+ "type": "array",
+ "description": "A list containing the metadata for the metrics in the report.",
+ "items": {
+ "$ref": "#/components/schemas/MetricMetadata"
+ }
+ },
+ "reportType": {
+ "type": "string",
+ "description": "The report_type, as specified in the request to create the report task.
Note: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type defines the fields included in the report."
+ },
+ "ReportMetadatas": {
+ "type": "object",
+ "properties": {
+ "reportMetadata": {
+ "type": "array",
+ "description": "A list of the metadata for the associated report type.",
+ "items": {
+ "$ref": "#/components/schemas/ReportMetadata"
+ }
+ }
+ },
+ "description": "This type defines the metadata used by the all report types."
+ },
+ "ReportTask": {
+ "type": "object",
+ "properties": {
+ "campaignIds": {
+ "type": "array",
+ "description": "A list of IDs for the campaigns that are included in the report. A campaign ID is a unique eBay-assigned identifier of the campaign that's generated when the campaign is created.
Call getCampaigns to return the current campaign IDs for a seller.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "channels": {
+ "type": "array",
+ "description": "The channel for the advertising campaign that will be included in the report task. This value indicates whether the data included in the report task is for an Onsite or Offsite advertising campaign.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "dateFrom": {
+ "type": "string",
+ "description": "The date defining the start of the timespan covered by the report, formatted as an ISO 8601 timestamp."
+ },
+ "dateTo": {
+ "type": "string",
+ "description": "The date defining the end of the timespan covered by the report, formatted as an ISO 8601 timestamp."
+ },
+ "dimensions": {
+ "type": "array",
+ "description": "A list containing the dimension in the report.",
+ "items": {
+ "$ref": "#/components/schemas/Dimension"
+ }
+ },
+ "fundingModels": {
+ "type": "array",
+ "description": "The funding model for the campaign that shall be included in the report.
Note: The default funding model for Promoted Listings reports is COST_PER_SALE.
Valid Values:COST_PER_SALECOST_PER_CLICK
",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "inventoryReferences": {
+ "type": "array",
+ "description": "If supplied in the request, this field returns a list of the seller's inventory reference IDs included in the report. Each item is referenced by a pair of inventoryRefernceID and inventoryReferenceType values, where an inventory reference ID can be either a seller-defined SKU value or an inventoryItemGroupKey. An inventoryItemGroupKey is seller-defined ID for an inventory item group (a multiple-variation listing), and is created and used by the Inventory API.
",
+ "items": {
+ "$ref": "#/components/schemas/InventoryReference"
+ }
+ },
+ "listingIds": {
+ "type": "array",
+ "description": "If supplied in the request, this field returns a list of the listing IDs included in the report. A listing ID is an eBay-assigned ID that's generated when a listing is created.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The ID of the eBay marketplace used by the report task. For implementation help, refer to eBay API documentation"
+ },
+ "metricKeys": {
+ "type": "array",
+ "description": "A list of metrics for the report task.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "reportExpirationDate": {
+ "type": "string",
+ "description": "The date after which the report is no longer be available. Reports are available for 30 days and you cannot download a report after it has expired.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
+ },
+ "reportFormat": {
+ "type": "string",
+ "description": "Indicates the format of the report. Currently, only TSV_GZIP is supported. For implementation help, refer to eBay API documentation"
+ },
+ "reportHref": {
+ "type": "string",
+ "description": "The URL of the generated report, which can be used to download the report once it has been generated."
+ },
+ "reportId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for the report."
+ },
+ "reportName": {
+ "type": "string",
+ "description": "An eBay-assigned name for the report that's created by the createReportTask call. This name is unique for the seller."
+ },
+ "reportTaskCompletionDate": {
+ "type": "string",
+ "description": "The date the report task completed the report generation.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
+ },
+ "reportTaskCreationDate": {
+ "type": "string",
+ "description": "The date the report task was created.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
+ },
+ "reportTaskExpectedCompletionDate": {
+ "type": "string",
+ "description": "The date the report task is expected to complete the report generation.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
+ },
+ "reportTaskId": {
+ "type": "string",
+ "description": "The unique eBay-assigned ID of the report task. This value is generated when the report task is created with a call to createReportTask."
+ },
+ "reportTaskStatus": {
+ "type": "string",
+ "description": "Indicates the current state of the report task. For implementation help, refer to eBay API documentation"
+ },
+ "reportTaskStatusMessage": {
+ "type": "string",
+ "description": "A status message with additional information about the report task."
+ },
+ "reportType": {
+ "type": "string",
+ "description": "Indicates type of report associated with the report task.
Note: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type defines the fields in a report task."
+ },
+ "ReportTaskPagedCollection": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the current page of results from the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.
Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
+ "format": "int32"
+ },
+ "reportTasks": {
+ "type": "array",
+ "description": "A list of report tasks contained on this page from the paginated response.",
+ "items": {
+ "$ref": "#/components/schemas/ReportTask"
+ }
+ }
+ },
+ "description": "This type defines the fields that paginate the reports tasks returned by the request. The entire result set consists of 0 or more sequenced response pages, where each page consists of 0 or more items from the complete result set."
+ },
+ "RuleCriteria": {
+ "type": "object",
+ "properties": {
+ "excludeInventoryItems": {
+ "type": "array",
+ "description": "A list of seller inventory reference IDs to exclude from the discount.
Note: The request can have either excludeInventoryItems or excludeListingIds but not both.
Maximum: 100 parent items
Maximum SKU or custom label length: 50 characters",
+ "items": {
+ "$ref": "#/components/schemas/InventoryItem"
+ }
+ },
+ "excludeListingIds": {
+ "type": "array",
+ "description": "A list of eBay listing IDs to exclude from the discount.
Note: The request can have either excludeInventoryItems or excludeListingIds but not both.
Maximum: 100 parent items
Maximum SKU or custom label length: 50 characters",
+ "items": {
+ "type": "string"
+ }
+ },
+ "markupInventoryItems": {
+ "type": "array",
+ "description": "A list of SKUs to remove from a markdown discount. The listed SKUs are 'marked up' to their standard price after being part of the markdown discount.",
+ "items": {
+ "$ref": "#/components/schemas/InventoryItem"
+ }
+ },
+ "markupListingIds": {
+ "type": "array",
+ "description": "A list of listing IDs to remove from a markdown discount. The listed items are 'marked up' to their standard price after being part of the markdown discount.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "selectionRules": {
+ "type": "array",
+ "description": "The container for the rules that select the items to be discounted.
Required if inventoryCriterionType is set to INVENTORY_BY_RULE.
For information on using the contained fields, see Item discounts.",
+ "items": {
+ "$ref": "#/components/schemas/SelectionRule"
+ }
+ }
+ },
+ "description": "This type defines the fields for a set of inventory selection rules.
Required: When inventoryCriterionType is set to INVENTORY_BY_RULE or INVENTORY_ANY."
+ },
+ "SelectedInventoryDiscount": {
+ "type": "object",
+ "properties": {
+ "discountBenefit": {
+ "description": "This container defines the discount as either a monetary amount or a percentage applied to the sales price.",
+ "$ref": "#/components/schemas/DiscountBenefit"
+ },
+ "discountId": {
+ "type": "string",
+ "description": "A unique, eBay-generated ID that you can use to identify the discount. This field is ignored in POST and PUT operations."
+ },
+ "inventoryCriterion": {
+ "description": "A container that defines either the listing IDs or the selection rules that specify the items to include in the discount. Listing IDs can be either eBay listing IDs or a list of the seller's inventory reference IDs (know as SKUs or custom labels). See the selectionRules container for the rule criteria you can use to select inventory. Note: All listings in Discounts Manager discounts must support an electronic payment method.
",
+ "$ref": "#/components/schemas/InventoryCriterion"
+ },
+ "ruleOrder": {
+ "type": "integer",
+ "description": "For markdown discounts, this field is reserved for future use. ",
+ "format": "int32"
+ }
+ },
+ "description": "This type defines the fields that describe the discounts applied to a set of inventory items and the order in which the selection rules are applied."
+ },
+ "SelectionRule": {
+ "type": "object",
+ "properties": {
+ "brands": {
+ "type": "array",
+ "description": "An array of product brands. For more details, see Using the selectionRules container.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "categoryIds": {
+ "type": "array",
+ "description": "This field contains an array of the associated category ID(s).
For Item discounts, a single-item array containing the category ID associated with the discounts. Required when used in an Item discount and either specifying a selectionRules container or when inventoryCriterionType is set to INVENTORY_BY_RULE.
For Promoted Listing campaigns, an array of category ID(s) associated with the campaign.
For information on how to get category IDs, see eBay Marketplace category IDs and Seller store category IDs",
+ "items": {
+ "type": "string"
+ }
+ },
+ "categoryScope": {
+ "type": "string",
+ "description": "This enumerated value indicates if the category ID for the item is an identifier for eBay categories or for a seller's eBay store categories.
For Promoted Listing campaigns, this field includes the type of the category ID for the item(s) to be included in the campaign.
For Item discounts, this field identifies the scope for the corresponding array as eBay categories or for a seller's eBay store categories. Required when used in an Item discount and inventoryCriterionType is set to INVENTORY_BY_RULE. For implementation help, refer to eBay API documentation"
+ },
+ "listingConditionIds": {
+ "type": "array",
+ "description": "A comma-separated list of unique identifiers for the conditions of listings to be included
For Promoted Listing campaigns, refer to Add items to the campaign. Up to four IDs can be specified.
For Item discounts, refer to Item condition ID and name values.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "maxPrice": {
+ "description": "This container sets the maximum price threshold. For more details, see Using the selectionRules container.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "minPrice": {
+ "description": "This container sets the minimum price threshold. For more details, see Using the selectionRules container.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type defines all rules/inclusion filters used to add listings to campaigns or discounts. Use of the specific fields is different for campaigns or discounts. See Using the selectionRules container."
+ },
+ "SuggestBudgetResponse": {
+ "type": "object",
+ "properties": {
+ "suggestedBudget": {
+ "type": "array",
+ "description": "The suggested allocated daily budget for an offsite campaign.",
+ "items": {
+ "$ref": "#/components/schemas/BudgetRecommendationResponse"
+ }
+ }
+ },
+ "description": "This type defines the fields used in the suggestBudget response."
+ },
+ "SuggestMaxCpcRequest": {
+ "type": "object",
+ "properties": {
+ "listingIds": {
+ "type": "array",
+ "description": "A comma delimited array of listing Ids the seller plans to associate with the smart targeting campaign for which the maxCpc will be suggested.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The unique identifier of the marketplace where the listings are hosted. See MarketplaceIdEnum for supported values. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type defines the fields used in the suggestMaxCpc request. To retrieve the suggested maxCpc value for a smart targeting campaign, a seller must specify the listings associated with the campaign, as well as the marketplace on which the campaign is hosted."
+ },
+ "SuggestMaxCpcResponse": {
+ "type": "object",
+ "properties": {
+ "amount": {
+ "description": "The suggested maxCpc amount for the smart targeting campaign.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The unique identifier of the marketplace where the listings are hosted. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type defines the fields used in the suggestMaxCpc response."
+ },
+ "SuggestedBids": {
+ "type": "object",
+ "properties": {
+ "keywordText": {
+ "type": "string",
+ "description": "The text for the keyword."
+ },
+ "matchType": {
+ "type": "string",
+ "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
+ },
+ "proposedBid": {
+ "description": "The suggested bid associated with the keyword. ",
+ "$ref": "#/components/schemas/ProposedBid"
+ }
+ },
+ "description": "The suggested bid rate for the item."
+ },
+ "SuggestedKeywords": {
+ "type": "object",
+ "properties": {
+ "additionalInfo": {
+ "type": "array",
+ "description": "A container for the additional information and compiled insight data for suggested keywords. ",
+ "items": {
+ "$ref": "#/components/schemas/AdditionalInfo"
+ }
+ },
+ "keywordText": {
+ "type": "string",
+ "description": "The text for the keyword."
+ },
+ "matchType": {
+ "type": "string",
+ "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "The suggested keywords for the item."
+ },
+ "SummaryReportResponse": {
+ "type": "object",
+ "properties": {
+ "baseSale": {
+ "description": "The total revenue from all the purchased items that were part of a discount but did not trigger a discount during the discount period.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "lastUpdated": {
+ "type": "string",
+ "description": "The date the report was generated."
+ },
+ "percentageSalesLift": {
+ "type": "string",
+ "description": "The percentage of the total dollar amount gained due to discounts. This value is calculated as follows:
precentageSalesLift = promotionSale / (baseSale + promotionSale)"
+ },
+ "promotionSale": {
+ "description": "The total revenue from all the purchased items that were part of a discount and their purchase did trigger a discount during the discount period.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "totalSale": {
+ "description": "Total dollar sales amount of all the seller's listings, current to the date the report was generated.",
+ "$ref": "#/components/schemas/Amount"
+ }
+ },
+ "description": "This type defines the fields in an Discounts Manager Summary report. Reports are formatted in JSON. For more details, see Reading item discount Summary reports."
+ },
+ "TargetedAdsPagedCollection": {
+ "type": "object",
+ "properties": {
+ "href": {
+ "type": "string",
+ "description": "The URI of the current page of results from the result set."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
+ "format": "int32"
+ },
+ "next": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set."
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Default: 0
Note: The items in a paginated result set use a zero-based list, where the first item in the list has an offset of 0.",
+ "format": "int32"
+ },
+ "prev": {
+ "type": "string",
+ "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results."
+ },
+ "suggestedItems": {
+ "type": "array",
+ "description": "A list of suggested items in the paginated collection.",
+ "items": {
+ "$ref": "#/components/schemas/TargetingItems"
+ }
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of items retrieved in the result set.
Note: If no items are found, this field is returned with a value of 0.",
+ "format": "int32"
+ }
+ },
+ "description": "A type that defines the keywords of the paged collection."
+ },
+ "TargetedBidRequest": {
+ "type": "object",
+ "properties": {
+ "keywords": {
+ "type": "array",
+ "description": "An array of keywords for which bids will be required.
Maximum number of keywords: 500",
+ "items": {
+ "$ref": "#/components/schemas/KeywordRequest"
+ }
+ }
+ },
+ "description": "A type that defines the targeted bid."
+ },
+ "TargetedBidsPagedCollection": {
+ "type": "object",
+ "properties": {
+ "suggestedBids": {
+ "type": "array",
+ "description": "A list of bids in the paginated collection.",
+ "items": {
+ "$ref": "#/components/schemas/SuggestedBids"
+ }
+ }
+ },
+ "description": "A type that defines the keywords of the paged collection."
+ },
+ "TargetedKeywordRequest": {
+ "type": "object",
+ "properties": {
+ "additionalInfo": {
+ "type": "array",
+ "description": "A field used to indicate whether additional information and insight data shall be provided for suggested keywords.
Use this array to retrieve keyword insights, including active seller count and search volume.
Valid Value: KEYWORD_INSIGHTS",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "exclusions": {
+ "type": "array",
+ "description": "A field used to indicate that the keywords already selected by sellers for the specified listing IDs should be filtered out of the response, and only new and unique keyword recommendations shall be returned.
Valid Value: ADOPTED_KEYWORDS",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "listingIds": {
+ "type": "array",
+ "description": "A set of comma-separated listing IDs for the specific listings you wish to retrieve suggested keywords.
Maximum number of listings requested: 300",
+ "items": {
+ "type": "string"
+ }
+ },
+ "matchType": {
+ "type": "string",
+ "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A type that provides details for the targeted keywords."
+ },
+ "TargetedKeywordsPagedCollection": {
+ "type": "object",
+ "properties": {
+ "suggestedKeywords": {
+ "type": "array",
+ "description": "A list of suggested keywords in the paged collection. Note: A relevancy check with items already present in the ad-group is performed even if item IDs associated with the ad-group are not explicitly passed in the request.
",
+ "items": {
+ "$ref": "#/components/schemas/SuggestedKeywords"
+ }
+ }
+ },
+ "description": "A type that defines the keywords of the paged collection."
+ },
+ "TargetingItems": {
+ "type": "object",
+ "properties": {
+ "bases": {
+ "type": "array",
+ "description": "The metrics and additional information for the items.",
+ "items": {
+ "$ref": "#/components/schemas/ItemBasis"
+ }
+ },
+ "listingId": {
+ "type": "string",
+ "description": "The listing ID of the targeted item."
+ }
+ },
+ "description": "A type that defines the targeted items."
+ },
+ "UpdateAdGroupRequest": {
+ "type": "object",
+ "properties": {
+ "adGroupStatus": {
+ "type": "string",
+ "description": "An enumeration value representing the current status of the ad group.If the status of the ad is currently ACTIVE, you can change status to PAUSED or ARCHIVED. If ad group is currently in PAUSED status, you can change the status back to ACTIVE. Ads that are currently in ARCHIVED status cannot be made ACTIVE again.
Valid Values:
For implementation help, refer to eBay API documentation"
+ },
+ "defaultBid": {
+ "description": "A bid amount that applies to all of the keywords in an ad group that do not have individual bids.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "name": {
+ "type": "string",
+ "description": "The updated name for the specified ad group."
+ }
+ },
+ "description": "A type that contains the fields used by the UpdateAdGroup request."
+ },
+ "UpdateAdStatusByListingIdRequest": {
+ "type": "object",
+ "properties": {
+ "adGroupId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model.
Use the getAdGroups method to retrieve the ad group IDs for a seller."
+ },
+ "adStatus": {
+ "type": "string",
+ "description": "An enumeration value representing the current status of the ad.
Valid Values: For implementation help, refer to eBay API documentation"
+ },
+ "listingId": {
+ "type": "string",
+ "description": "A unique eBay-assigned identifier for a listing that is generated when the listing is created.
Note: This field accepts both listing IDs (as generated by the Inventory API), and item IDs (as used in the eBay Traditional API set, such as the Trading and Finding APIs)."
+ }
+ },
+ "description": "A type that contains the fields for the UpdateAdStatusByListingId request."
+ },
+ "UpdateAdStatusRequest": {
+ "type": "object",
+ "properties": {
+ "adId": {
+ "type": "string",
+ "description": "A unique eBay-assigned identifier for an ad that belongs to the specified campaign.
Use the getAds method to retrieve ad IDs."
+ },
+ "adStatus": {
+ "type": "string",
+ "description": "An enumeration value representing the status you wish to update the specified ad to.
Valid Values: For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A type that contains the fields for the UpdateAdStatus request."
+ },
+ "UpdateAdrateStrategyRequest": {
+ "type": "object",
+ "properties": {
+ "adRateStrategy": {
+ "type": "string",
+ "description": "This field is used to change the current ad rate strategy for a Cost Per Sale (CPS) campaign. It is not needed if the ad rate strategy is not being changed for the campaign.
Note: This field is not applicable for offsite campaigns. For implementation help, refer to eBay API documentation"
+ },
+ "bidPercentage": {
+ "type": "string",
+ "description": "The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
This is the default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.
Note: This field has a minimum value of 2.0 and a maximum value of 100.0."
+ },
+ "dynamicAdRatePreferences": {
+ "type": "array",
+ "description": "A field that indicates whether a single, user-defined bid percentage (also known as the ad rate) should be used, or whether eBay should automatically adjust listings to maintain the daily suggested bid percentage.
Note: Dynamic adjustment is only applicable when the adRateStrategy is set to DYNAMIC.
Default: FIXED",
+ "items": {
+ "$ref": "#/components/schemas/DynamicAdRatePreference"
+ }
+ }
+ },
+ "description": "A type that defines the request fields used to update the ad rate strategy for a Promoted Listings ad campaign."
+ },
+ "UpdateAdsByInventoryReferenceResponse": {
+ "type": "object",
+ "properties": {
+ "ads": {
+ "type": "array",
+ "description": "A list of ad IDs and links to retrieve them.",
+ "items": {
+ "$ref": "#/components/schemas/AdReference"
+ }
+ },
+ "errors": {
+ "type": "array",
+ "description": "A container for all of the errors associated with the specified inventory reference ID.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "inventoryReferenceId": {
+ "type": "string",
+ "description": "The reference ID associated with the ad. The reference ID could be a SKU number or Inventory Item Group, depending on value of inventoryReferenceType."
+ },
+ "inventoryReferenceType": {
+ "type": "string",
+ "description": "The inventory reference type associated with the ad. The inventory reference type could be a SKU number or Inventory Item Group. For implementation help, refer to eBay API documentation"
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "An HTTP status code that indicates whether or not the CPS ad was successfully updated.",
+ "format": "int32"
+ }
+ },
+ "description": "A type that contains the response fields used by the UpdateAdsByInventoryReference method."
+ },
+ "UpdateBidPercentageRequest": {
+ "type": "object",
+ "properties": {
+ "bidPercentage": {
+ "type": "string",
+ "description": "The updated bid percentage value for the specified ad in the specified campaign. The bid percentage (also known as the ad rate) is a user-defined value which sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
Note: This field has a minimum value of 2.0 and a maximum value of 100.0."
+ }
+ },
+ "description": "This type specifies the bid percentage for an ad campaign."
+ },
+ "UpdateBiddingStrategyRequest": {
+ "type": "object",
+ "properties": {
+ "biddingStrategy": {
+ "type": "string",
+ "description": "The new bidding strategy for the specified Cost Per Click (CPC) campaign. For implementation help, refer to eBay API documentation"
+ },
+ "bidPreferences": {
+ "type": "array",
+ "description": "This container indicates the bidding preferences of the campaign, such as the maximum CPC amount.
Note: This container is only applicable for smart targeting campaigns.
This container is required if the user wants to create a Smart Targeting campaign.",
+ "items": {
+ "$ref": "#/components/schemas/BidPreference"
+ }
+ }
+ },
+ "description": "This type defines the fields used in the updatedBiddingStrategy request."
+ },
+ "UpdateCampaignBudgetRequest": {
+ "type": "object",
+ "properties": {
+ "daily": {
+ "description": "The daily budget limit for the Cost Per Click (CPC) Promoted Listings campaign. This will be a dollar value. All clicks using the keywords defined for the campaign will go towards expending the daily budget. Once the daily budget is exceeded for the campaign, all Promoted Listings under the campaign will be turned off until the next day.
Valid Values:",
+ "$ref": "#/components/schemas/BudgetRequest"
+ }
+ },
+ "description": "A type that contains the fields for the UpdateCampaignBudget request."
+ },
+ "UpdateCampaignIdentificationRequest": {
+ "type": "object",
+ "properties": {
+ "campaignName": {
+ "type": "string",
+ "description": "The new seller-defined name for the campaign. This value must be unique for the seller. If you don't want to change the name of the campaign, specify the current campaign name in this field.
You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters."
+ },
+ "endDate": {
+ "type": "string",
+ "description": "The date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is omitted, the campaign will have no defined end date, and will not end until the seller makes a decision to end the campaign with an endCampaign call, or if they update the campaign at a later time with an end date.If you want to change only the end date of the campaign, you must specify the current campaign name, set the endDate as desired, and set the startDate to the actual start date of the campaign. This applies if the campaign status is RUNNING or PAUSED. You can retrieve the startDate using the getCampaign method.
Note that if you do not set a new end date in this call, any current endDate value will be set to null. To preserve the currently-set end date, you must specify the value again in your request.
"
+ },
+ "startDate": {
+ "type": "string",
+ "description": "The new start date for the campaign, in UTC format (yyyy-MM-ddThh:mm:ssZ).If the campaign status is RUNNING or PAUSED, the startDate must be specified and must be the actual start date of the campaign, even if you are only changing the endDate. You can retrieve the campaign's startDate using the getCampaign method.
On the date specified, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts after this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign.
Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.
"
+ }
+ },
+ "description": "This type specifies the updated name, and start and end dates for an update-campaign request."
+ },
+ "UpdateCampaignRequest": {
+ "type": "object",
+ "properties": {
+ "audienceCodes": {
+ "type": "array",
+ "description": "An array of audience codes for the audiences of the email campaign. At least one audience code is required. There is no limit to the number of audience codes that may be entered.
Example: if the current email campaign contains \"audienceCodes\": \"code1\", \"code2\" and the user wishes to add an audience code code3, set the audienceCodes value to \"audienceCodes\": \"code1\", \"code2\", \"code3\".
To retrieve seller audiences, call getAudiences. Use the code values in the response to populate audienceCodes.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of either an eBay category or a store category.
This field is used if a seller wants to apply an email campaign to a specific eBay category or store category. The categoryType determines whether the categoryId value is an eBay category or store category.
Use the Taxonomy API to retrieve eBay categories. To retrieve seller store categories, use the getStore call. Use the categoryId value of the desired category from the results as the value in the request.
itemSelectMode must be set to AUTO in order to use a category ID."
+ },
+ "categoryType": {
+ "type": "string",
+ "description": "This field must be set when applying an email campaign to a specific eBay category or store category. The enumeration value used indicates which type of category the categoryId belongs to. For implementation help, refer to eBay API documentation"
+ },
+ "itemIds": {
+ "type": "array",
+ "description": "An array of unique identifiers for the listings displayed in an email campaign. Used if the seller wishes to select the eBay listings in the email campaign rather than have eBay automatically select them.
Call getSellerList to retrieve all seller listings. Each Item result contains an ItemID value. Use this value in itemIds to feature that listing.
The maximum number of itemIds for the COUPON campaign type is 4, and for every other campaign type is 10.
itemSelectMode must be set to MANUAL in order to use this field.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "itemSelectMode": {
+ "type": "string",
+ "description": "Determines whether listings featured in an email campaign are selected by the seller or by eBay.
If itemSelectMode is set to AUTO, eBay automatically choses listings based on values set for sort, categoryType, categoryId, and priceRange.
If itemSelectMode is set to MANUAL, listings are set by the seller by populating the itemIds array.
Note: itemSelectMode is always set to AUTO for WELCOME email campaigns. For implementation help, refer to eBay API documentation"
+ },
+ "personalizedMessage": {
+ "type": "string",
+ "description": "The body of the email campaign. Accepts HTML and CSS. The maximum length is 1000 characters"
+ },
+ "priceRange": {
+ "description": "This container is used if the seller wants to apply the email campaign to listings based on a price range.
The priceRange container consists of the currency, gte, and lte fields.
\"gte\" stands for \"greater than or equal to\" and \"lte\" stands for \"less than or equal to\". Either gte, lte, or both must be used if the seller wishes to include a price range.
Note: Use this object when the itemSelectMode is set to AUTO.",
+ "$ref": "#/components/schemas/PriceRange"
+ },
+ "promotionId": {
+ "type": "string",
+ "description": "The ID of the discount used for an email campaign if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT, and promotionSelectModeEnum is set to MANUAL.
To find a discount, call getPromotions to retrieve a list of the seller's discounts. Use the promotionId from an individual PromotionDetail result for the request."
+ },
+ "promotionSelectModeEnum": {
+ "type": "string",
+ "description": "The selection mode for the discount used. If set to AUTO, eBay will choose the discount to include in the email campaign. If set to MANUAL, the seller must specify the discount in the promotionId field.
This field is required if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT. For implementation help, refer to eBay API documentation"
+ },
+ "scheduleDate": {
+ "type": "string",
+ "description": "The date and time that the email campaign newsletter will be sent, given in UTC format. Example: 2023-05-20T03:13:35Z
This field should be used if the seller wishes to send the email campaign on a future date. If no scheduleDate is set, the email campaign will send once it is created or updated."
+ },
+ "sort": {
+ "type": "string",
+ "description": "The sort rule is used to display the listings featured in the email campaign.
Sort rules are only used if itemSelectMode is set to AUTO. If itemSelectMode is MANUAL, listings are displayed in the order in which they are listed in the itemIds array.
The following sort rules are available:ENDING_FIRST displays listings by ending date, from soonest to latest.LOWEST_PRICED displays listings by price, from lowest to highest.HIGHEST_PRICED displays listings by price, from highest to lowest.NEWLY_LISTED displays listings by date listed, with the newest first.
The default sort rule is NEWLY_LISTED. For implementation help, refer to eBay API documentation"
+ },
+ "subject": {
+ "type": "string",
+ "description": "The email campaign subject. The maximum length is 70 characters."
+ }
+ },
+ "description": "The update email campaign request payload"
+ },
+ "UpdateEmailCampaignResponse": {
+ "type": "object",
+ "properties": {
+ "emailCampaignId": {
+ "type": "string",
+ "description": "The unique eBay-assigned ID to the email campaign that is generated when the email campaign is created."
+ },
+ "emailCampaignStatus": {
+ "type": "string",
+ "description": "The email campaign status. See EmailCampaignStatusEnum for a list of email campaign statuses and their descriptions. For implementation help, refer to eBay API documentation"
+ }
}
- }
+ },
+ "UpdateKeywordByKeywordIdRequest": {
+ "type": "object",
+ "properties": {
+ "bid": {
+ "description": "This container is used to set or change the bid percentage for the keyword. Each time a listing is retrieved in search results using this keyword and clicked on, the seller will be charged this amount. Each click goes toward the daily budget set up for the Cost Per Click (CPC) campaign.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "keywordId": {
+ "type": "string",
+ "description": "This field is used to identify the keyword to be updated. The getKeyword method can be used to retrieve keywordId values."
+ },
+ "keywordStatus": {
+ "type": "string",
+ "description": "Include this field if you wish to change the status of the keyword. The status value specified here must be different than the keyword's current status. To confirm the current status of a keyword, you can use the getKeyword method.If the status of the ad is currently ACTIVE, you can change status to PAUSED or ARCHIVED. If ad group is currently in PAUSED status, you can change the status back to ACTIVE. Ads that are currently in ARCHIVED status cannot be made ACTIVE again. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A type that contains the fields for the UpdateKeywordByKeywordId request."
+ },
+ "UpdateKeywordRequest": {
+ "type": "object",
+ "properties": {
+ "bid": {
+ "description": "This container is used to set or change the bid for the keyword. Each time a listing is retrieved in search results using this keyword and clicked on, the seller will be charged this amount. Each click goes toward the daily budget set up for the CPC campaign. If the bid is not provided, then the default bid associated with the ad group is used.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "keywordStatus": {
+ "type": "string",
+ "description": "Include this field if you wish to change the status of the keyword. The status value specified here must be different than the keyword's current status. To confirm the current status of a keyword, you can use the getKeyword method.
If the status of the ad is currently ACTIVE, you can change status to PAUSED or ARCHIVED. If ad group is currently in PAUSED status, you can change the status back to ACTIVE. Ads that are currently in ARCHIVED status cannot be made ACTIVE again. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A type that contains the fields for the UpdateKeyword request."
+ },
+ "UpdateKeywordResponse": {
+ "type": "object",
+ "properties": {
+ "errors": {
+ "type": "array",
+ "description": "This container will be returned if there are one or more issues associated with modifying the corresponding keyword.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "keywordId": {
+ "type": "string",
+ "description": "This field identifies the keyword that the seller updated, or attempted to update."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "An HTTP status code is returned for each keyword to indicate the success or failure of updating that keyword.",
+ "format": "int32"
+ },
+ "warnings": {
+ "type": "array",
+ "description": "List of warnings associated with this operation",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "A type that contains the fields for the UpdateKeyword response."
+ },
+ "UpdateNegativeKeywordIdRequest": {
+ "type": "object",
+ "properties": {
+ "negativeKeywordId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for a negative keyword. This keyword ID will be generated for each successfully created negative keyword.
Use the getNegativeKeywords method to retrieve negative keyword IDs."
+ },
+ "negativeKeywordStatus": {
+ "type": "string",
+ "description": "A field that defines the status of the negative keyword.
See NegativeKeywordStatusEnum for supported values. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A type that defines the fields used to update a negative keyword."
+ },
+ "UpdateNegativeKeywordRequest": {
+ "type": "object",
+ "properties": {
+ "negativeKeywordStatus": {
+ "type": "string",
+ "description": "A field that defines the status of the negative keyword. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A type that contains the fields for the UpdateNegativeKeyword request."
+ },
+ "UpdateNegativeKeywordResponse": {
+ "type": "object",
+ "properties": {
+ "errors": {
+ "type": "array",
+ "description": "A container that will be returned if there are one or more issues associated with modifying the corresponding negative keyword.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "negativeKeywordId": {
+ "type": "string",
+ "description": "A unique eBay-assigned ID for a negative keyword. This keyword ID will be generated for each successfully created negative keyword."
+ },
+ "statusCode": {
+ "type": "integer",
+ "description": "An HTTP status code that indicates the success or failure of updating that negative keyword.",
+ "format": "int32"
+ }
+ },
+ "description": "A type that contains the fields for the UpdateNegativeKeyword response."
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/suggest_items": {
- "get": {
- "tags": [
- "campaign"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method allows sellers to obtain ideas for listings, which can be targeted for Promoted Listings campaigns.",
- "operationId": "suggestItems",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "category_ids",
- "in": "query",
- "description": "Specifies the category ID that is used to limit the results. This refers to an exact leaf category (the lowest level in that category and has no children). This field can have one category ID, or a comma-separated list of IDs. To return all category IDs, set to null.
Maximum: 10 ",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "limit",
- "in": "query",
- "description": "Specifies the maximum number of campaigns to return on a page in the paginated response. If no value is specified, the default value is used.
Default: 10
Minimum: 1
Maximum: 1000",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "Specifies the number of campaigns to skip in the result set before returning the first report in the paginated response.
Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/TargetedAdsPagedCollection"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35008": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The category Id {categoryId} is not valid."
- },
- "35029": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
- },
- "35030": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'offset' cannot be less than zero."
- },
- "35041": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'marketplaceId' is required."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "35090": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Category ID limit exceeded. You can pass up to a maximum of {maxCategoryLimit} category IDs per request."
+ "securitySchemes": {
+ "api_auth": {
+ "type": "oauth2",
+ "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
+ "flows": {
+ "clientCredentials": {
+ "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
+ "scopes": {
+ "https://api.ebay.com/oauth/api_scope": "View public data from eBay"
+ }
+ },
+ "authorizationCode": {
+ "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
+ "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
+ "scopes": {
+ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly": "View your eBay marketing activities, such as ad campaigns and listing promotions",
+ "https://api.ebay.com/oauth/api_scope/sell.marketing": "View and manage your eBay marketing activities, such as ad campaigns and listing promotions"
+ }
+ }
}
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35051": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/update_ad_rate_strategy": {
- "post": {
- "tags": [
- "campaign"
- ],
- "description": "This method updates the ad rate strategy for an existing Promoted Listings Standard (PLS) rules-based ad campaign that uses the Cost Per Sale (CPS) funding model.
Specify the campaign_id as a path parameter. You can retrieve the campaign IDs for a seller by calling the getCampaigns method.
Note: This method only applies to the CPS funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.",
- "operationId": "updateAdRateStrategy",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This type defines the request fields for the ad rate strategy that shall be updated.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the request fields for the ad rate strategy that shall be updated.",
- "$ref": "#/components/schemas/UpdateAdrateStrategyRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "204": {
- "description": "No content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35007": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35043": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign status of {campaignStatus} is either invalid or not supported for this operation."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35106": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'BidPercentage' should be provided when selected 'adRateStrategy' is 'FIXED'."
- },
- "35107": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "'dynamicAdRatePreferences' can be provided only when selected 'adRateStrategy' is 'DYNAMIC'."
- },
- "35108": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'adRateAdjustmentPercent' {adRateAdjustmentPercent} is not valid. Please set 'adRateAdjustmentPercent' {adRateAdjustmentPercent} between {minAllowedAdRateAdjustmentPercent}% - {maxAllowedAdRateAdjustmentPercent}%."
- },
- "35109": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'adRateCapPercent' {adRateCapPercent} is not valid. Please set 'adRateCapPercent' between {minAllowedAdRateCapPercent}% - {maxAllowedAdRateCapPercent}%."
- },
- "35110": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'adRateStrategy' is not supported for CPC funding model."
- },
- "35111": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'dynamicAdRatePreferences' is not supported for CPC funding model."
- },
- "35114": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'dynamicAdRatePreferences' list currently can only support one element containing dynamicAdRatePreference. Please remove additional elements and try again."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/update_campaign_budget": {
- "post": {
- "tags": [
- "campaign"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method updates the daily budget for a PLA campaign that uses the Cost Per Click (CPC) funding model.
A click occurs when an eBay user finds and clicks on the sellerās listing (within the search results) after using a keyword that the seller has created for the campaign. For each ad in an ad group in the campaign, each click triggers a cost, which gets subtracted from the campaignās daily budget. If the cost of the clicks exceeds the daily budget, the Promoted Listings campaign will be paused until the next day.
Specify the campaign_id as a path parameter. You can retrieve the campaign IDs for a seller by calling the getCampaigns method.",
- "operationId": "updateCampaignBudget",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This type defines the request fields for the budget details that shall be updated.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the request fields for the budget details that shall be updated.",
- "$ref": "#/components/schemas/UpdateCampaignBudgetRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "204": {
- "description": "No content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36100": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This functionality is not supported for CPS funding model."
- },
- "36101": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The daily budget value format is a maximum of two decimal points."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "36153": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget currency {currency} is not supported for {fieldName}. The supported currency for the {marketplaceId} marketplace is {supportedCurrencyCode}."
- },
- "36154": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget below minimum allowed {minAllowed}."
- },
- "36155": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget above maximum allowed {maxAllowed}."
- },
- "36156": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "campaignBudget is not supported for CPS funding model."
- },
- "36157": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget is required for campaigns with CPC funding model."
- },
- "36158": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The daily budget value format {dailyBudgetValue} cannot have more than 2 decimal places."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/update_campaign_identification": {
- "post": {
- "tags": [
- "campaign"
- ],
- "description": "This method can be used to change the name of a campaign, as well as modify the start or end dates. Specify the campaign_id you want to update as a URI parameter, and configure the campaignName and startDate in the request payload.
If you want to change only the end date of the campaign, specify the current campaign name, set endDate as desired, and set startDate to the actual start date of the campaign. This applies if the campaign status is RUNNING or PAUSED. You can retrieve the startDate using the getCampaign method.
Note that if you do not set a new end date in this call, any current endDate value will be set to null. To preserve the currently-set end date, you must specify the value again in your request.
Call getCampaigns to retrieve a seller's campaign details, including the campaign ID, campaign name, and the start and end dates of the campaign.",
- "operationId": "updateCampaignIdentification",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This type defines the fields to update the campaign name and start and end dates.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the fields to update the campaign name and start and end dates.",
- "$ref": "#/components/schemas/UpdateCampaignIdentificationRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "204": {
- "description": "No content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35019": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Campaign name is required for this call."
- },
- "35020": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
- },
- "35021": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign with the name of {campaignName} already exists. Please provide a different name."
- },
- "35023": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
- },
- "35024": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign start date {startDate} cannot be after the end date {endDate}."
- },
- "35025": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign start date is required."
- },
- "35026": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A campaign start or end date {date} cannot be in the past."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35055": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The start date cannot be modified for an active campaign."
- },
- "35061": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again."
- },
- "35063": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
- },
- "35077": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity."
- },
- "35078": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
- },
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/bulk_create_keyword": {
- "post": {
- "tags": [
- "keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method adds keywords, in bulk, to an existing PLA ad group in a campaign that uses the Cost Per Click (CPC) funding model.
This method also sets the CPC rate for each keyword.
In the request, supply the campaign_id as a path parameter.
Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller.",
- "operationId": "bulkCreateKeyword",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "A type that defines the fields for the bulk request to create keywords.",
- "content": {
- "application/json": {
- "schema": {
- "description": "A type that defines the fields for the bulk request to create keywords.",
- "$ref": "#/components/schemas/BulkCreateKeywordRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkCreateKeywordResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35033": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one request is required for bulk requests."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No ad group found for ad group id {ad_group_id}."
- },
- "36219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The ad group with ad group id {ad_group_id} has been archived."
- },
- "36301": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keyword match type {matchType} is not supported. Valid values are: {matchTypeValues}."
- },
- "36303": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A keyword with text {keywordText} and match type {matchType} already exists for this Ad Group."
- },
- "36304": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keywordText {keywordText} cannot be more than {maxKeywordTextLength} characters."
- },
- "36305": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is not valid. The default bid value should be a double precision value."
- },
- "36306": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is below floor value {bidFloorValue}."
- },
- "36307": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is above max value {bidMaxValue}."
- },
- "36308": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' currency {bidCurrency} is not valid or missing."
- },
- "36309": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' currency {bidCurrency} should be the same as the daily budget."
- },
- "36311": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keywordText cannot be null or empty."
- },
- "36312": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keywordText contains invalid characters {invalidCharacters}"
- },
- "36313": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is more than maximum daily budget {maxDailyBudget}."
- },
- "36315": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "There are duplicate KeywordText and matchType combination in this request. You must remove the duplicate."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "36316": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of Keyword requests in a bulk request. Only {maxSupportedRequestNumberInBulk} Ids are supported per call."
- },
- "36319": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of create Keyword for an Ad Group. Only {maxSupportedNumber} Ids are supported per Ad Group."
- },
- "36320": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The keywordText {keywordText} cannot have total number of words more than {maxWordsInKeyword} words."
- },
- "36322": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "Total keyword requests exceed the current AdGroup keyword capacity, which is {maxSupportedRequestNumber}."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/bulk_update_keyword": {
- "post": {
- "tags": [
- "keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method updates the bids and statuses of keywords, in bulk, for an existing PLA campaign.
In the request, supply the campaign_id as a path parameter.
Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller.",
- "operationId": "bulkUpdateKeyword",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "A type that defines the fields for the bulk request to update keywords.",
- "content": {
- "application/json": {
- "schema": {
- "description": "A type that defines the fields for the bulk request to update keywords.",
- "$ref": "#/components/schemas/BulkUpdateKeywordRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkUpdateKeywordResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36305": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is not valid. The default bid value should be a double precision value."
- },
- "36306": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is below floor value {bidFloorValue}."
- },
- "36307": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is above max value {bidMaxValue}."
- },
- "36308": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' currency {bidCurrency} is not valid or missing."
- },
- "36309": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' currency {bidCurrency} should be the same as the daily budget."
- },
- "36310": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No keyword found for keyword id {keyword_id}."
- },
- "36313": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is more than maximum daily budget {maxDailyBudget}."
- },
- "36317": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' or 'keywordStatus' is missing, either one is required for update."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "36316": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of Keyword requests in a bulk. Only {maxSupportedNumberInBulk} Ids are supported per call."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/keyword": {
- "get": {
- "tags": [
- "keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method can be used to retrieve all of the keywords for ad groups in PLA campaigns that use the Cost Per Click (CPC) funding model.
In the request, specify the campaign_id as a path parameter. If one or more ad_group_ids are passed in the request body, the keywords for those ad groups will be returned. If ad_group_ids are not passed in the response body, the call will return all the keywords in the campaign.
Call the getCampaigns method to retrieve a list of current campaign IDs for a seller.",
- "operationId": "getKeywords",
- "parameters": [
- {
- "name": "ad_group_ids",
- "in": "query",
- "description": "A comma-separated list of ad group IDs. This query parameter is used if the seller wants to retrieve keywords from one or more specific ad groups. If this query parameter is not used, all keywords that are part of the CPC campaign are returned.Note:You can call the getAdGroups method to retrieve the ad group IDs for a seller.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "keyword_status",
- "in": "query",
- "description": "A comma-separated list of keyword statuses. The results will be filtered to only include the given statuses of the keyword. If none are provided, all keywords are returned.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "limit",
- "in": "query",
- "description": "
Specifies the maximum number of results to return on a page in the paginated response.
Default: 10
Maximum: 500",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "Specifies the number of results to skip in the result set before returning the first report in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/KeywordPagedCollectionResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35029": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
- },
- "35030": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'offset' cannot be less than zero."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36314": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Ad Group Ids should be delimited by {adGroupIdsDelimiter}"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error"
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "post": {
- "tags": [
- "keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method creates keywords using a specified campaign ID for an existing PLA campaign.
In the request, supply the campaign_id as a path parameter.
Call the suggestKeywords method to retrieve a list of keyword ideas to be targeted for PLA campaigns, and call the getCampaigns method to retrieve a list of current campaign IDs for a seller.",
- "operationId": "createKeyword",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "A type that defines the fields for the request to create a keyword.",
- "content": {
- "application/json": {
- "schema": {
- "description": "A type that defines the fields for the request to create a keyword.",
- "$ref": "#/components/schemas/CreateKeywordRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "201": {
- "description": "Created",
- "headers": {
- "Location": {
- "schema": {
- "type": "string",
- "description": "The location response header contains the getKeyword URI of the newly created keyword. The URI includes the newly created keywordId, which you can use to reference the keyword."
- }
- }
- },
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No ad group found for ad group id {ad_group_id}."
- },
- "36219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The ad group with ad group id {ad_group_id} has been archived."
- },
- "36301": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keyword match type {matchType} is not supported. Valid values are: {matchTypeValues}."
- },
- "36303": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A keyword with text {keywordText} and match type {matchType} already exists for this Ad Group."
- },
- "36304": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keywordText {keywordText} cannot be more than {maxKeywordTextLength} characters."
- },
- "36305": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is not valid. The default bid value should be a double precision value."
- },
- "36306": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is below floor value {bidFloorValue}."
- },
- "36307": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is above max value {bidMaxValue}."
- },
- "36308": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' currency {bidCurrency} is not valid or missing."
- },
- "36309": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' currency {bidCurrency} should be the same as the daily budget."
- },
- "36311": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keywordText cannot be null or empty."
- },
- "36312": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keywordText contains invalid characters {invalidCharacters}"
- },
- "36313": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is more than maximum daily budget {maxDailyBudget}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- },
- "36319": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of create Keyword for an Ad Group. Only {maxSupportedNumber} Ids are supported per Ad Group."
- },
- "36320": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The keywordText {keywordText} cannot have total number of words more than {maxWordsInKeyword} words."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_campaign/{campaign_id}/keyword/{keyword_id}": {
- "get": {
- "tags": [
- "keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method retrieves details on a specific keyword from an ad group within a PLA campaign that uses the Cost Per Click (CPC) funding model.
In the request, specify the campaign_id and keyword_id as path parameters.
Call the getCampaigns method to retrieve a list of current campaign IDs for a seller and call the getKeywords method to retrieve their keyword IDs.",
- "operationId": "getKeyword",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "keyword_id",
- "in": "path",
- "description": "This path parameter is used to identify the keyword to retrieve.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Keyword"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36310": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No keyword found for keyword id {keyword_id}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "put": {
- "tags": [
- "keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method updates keywords using a campaign ID and keyword ID for an existing PLA campaign.
In the request, specify the campaign_id and keyword_id as path parameters.
Call the getCampaigns method to retrieve a list of current campaign IDs for a seller and call the getKeywords method to retrieve their keyword IDs.",
- "operationId": "updateKeyword",
- "parameters": [
- {
- "name": "campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
Note: You can retrieve the campaign IDs for a specified seller using the getCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "keyword_id",
- "in": "path",
- "description": "A unique eBay-assigned ID that is generated when a keyword is created.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "A type that defines the fields for the request to update a keyword.",
- "content": {
- "application/json": {
- "schema": {
- "description": "A type that defines the fields for the request to update a keyword.",
- "$ref": "#/components/schemas/UpdateKeywordRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "204": {
- "description": "Success"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36305": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is not valid. The default bid value should be a double precision value."
- },
- "36306": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is below floor value {bidFloorValue}."
- },
- "36307": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is above max value {bidMaxValue}."
- },
- "36308": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' currency {bidCurrency} is not valid or missing."
- },
- "36309": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' currency {bidCurrency} should be the same as the daily budget."
- },
- "36310": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No keyword found for keyword id {keyword_id}."
- },
- "36313": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' value {bidValue} is more than maximum daily budget {maxDailyBudget}."
- },
- "36317": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'bid' or 'keywordStatus' is missing, either one is required for update."
- },
- "36318": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The keyword with 'keyword_id' {keyword_Id} is already archived and cannot be updated."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- },
- "35002": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal error. Please wait a few minutes and try the call again."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/bulk_create_negative_keyword": {
- "post": {
- "tags": [
- "negative_keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method adds negative keywords, in bulk, to an existing ad group in a PLA campaign that uses the Cost Per Click (CPC) funding model.
Specify the campaignId and adGroupId in the request body, along with the negativeKeywordText and negativeKeywordMatchType.
Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller.",
- "operationId": "bulkCreateNegativeKeyword",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "A type that defines the fields for the bulk request to create negative keywords.",
- "content": {
- "application/json": {
- "schema": {
- "description": "A type that defines the fields for the bulk request to create negative keywords.",
- "$ref": "#/components/schemas/BulkCreateNegativeKeywordRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkCreateNegativeKeywordResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35033": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one request is required for bulk requests."
- },
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No ad group found for ad group id {ad_group_id}."
- },
- "36219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The ad group with ad group id {ad_group_id} has been archived."
- },
- "36323": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' {negativeKeywordText} and 'negativeKeywordMatchType' {negativeKeywordMatchType} already exists for this Campaign."
- },
- "36330": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The provided negative keyword match type is not supported. Valid values are: {negativeKeywordMatchTypeValues}."
- },
- "36331": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' {negativeKeywordText} and 'negativeKeywordMatchType' {negativeKeywordMatchType} already exists for this Ad Group."
- },
- "36332": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' {negativeKeywordText} cannot be more than {maxNegativeKeywordTextLength} characters."
- },
- "36333": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' cannot be null or empty"
- },
- "36334": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' contains invalid characters {invalidCharacters}"
- },
- "36335": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You have exceeded the maximum number of negative keyword for an ad group. Only {maxSupportedNegativeKeywordNumber} Ids are supported per ad group."
- },
- "36336": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' {negativeKeywordText} cannot have total number of words more than {maxWordsInNegativeKeyword} words."
- },
- "36337": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You have exceeded the maximum number of negative keyword requests in a bulk. Only {maxSupportedNegativeKeywordRequestNumberInBulk} Ids are supported per call."
- },
- "36338": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "There are duplicate 'negativeKeywordText' and 'negativeKeywordMatchType' combination in this request. You must remove the duplicate(s)."
- },
- "36339": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Total negative keyword requests exceed the current AdGroup negative keyword capacity, which is {maxSupportedNegativeKeywordRequestNumber}."
- },
- "36345": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'campaignId' and 'adGroupId' are required."
- },
- "36346": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You have exceeded the maximum number of negative keyword for a campaign. Only {maxSupportedNegativeKeywordNumberCampaign} Ids are supported per campaign."
- }
- }
- }
- },
- "403": {
- "description": "Forbidden"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/bulk_update_negative_keyword": {
- "post": {
- "tags": [
- "negative_keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method updates the statuses of existing negative keywords, in bulk.
Specify the negativeKeywordId and negativeKeywordStatus in the request body.",
- "operationId": "bulkUpdateNegativeKeyword",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "A type that defines the fields for the bulk request to update negative keyword statuses.",
- "content": {
- "application/json": {
- "schema": {
- "description": "A type that defines the fields for the bulk request to update negative keyword statuses.",
- "$ref": "#/components/schemas/BulkUpdateNegativeKeywordRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BulkUpdateNegativeKeywordResponse"
- }
- }
- }
- },
- "207": {
- "description": "Multi Status"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "36337": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You have exceeded the maximum number of negative keyword requests in a bulk. Only {maxSupportedNegativeKeywordRequestNumberInBulk} Ids are supported per call."
- },
- "36340": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No negative keyword found for negative keyword id {negativeKeywordId}."
- },
- "36341": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "There are duplicate negative keyword Ids in this request. You must remove the duplicate(s)."
- },
- "36342": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "NegativeKeywordStatus is missing or invalid. It is required for update."
- },
- "36343": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Negative keyword with negative keyword id {negativeKeywordId} is already archived and cannot be updated."
- },
- "36348": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Negative keyword id 'negativeKeywordId' is required."
- },
- "36349": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'negativeKeywordId' is invalid."
- }
- }
- }
- },
- "403": {
- "description": "Forbidden"
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/negative_keyword": {
- "get": {
- "tags": [
- "negative_keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method can be used to retrieve all of the negative keywords for ad groups in PLA campaigns that use the Cost Per Click (CPC) funding model.
The results can be filtered using the campaign_ids, ad_group_ids, and negative_keyword_status query parameters.
Call the getCampaigns method to retrieve a list of current campaign IDs for a seller.",
- "operationId": "getNegativeKeywords",
- "parameters": [
- {
- "name": "ad_group_ids",
- "in": "query",
- "description": "A comma-separated list of ad group IDs.
This query parameter is used if the seller wants to retrieve the negative keywords from one or more specific ad groups. The results might not include these ad group IDs if other search conditions exclude them.
Note:You can call the getAdGroups method to retrieve the ad group IDs for a seller.
Required if the search results must be filtered to include negative keywords created at the ad group level.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "campaign_ids",
- "in": "query",
- "description": "A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created.
This query parameter is used if the seller wants to retrieve the negative keywords from a specific campaign. The results might not include these campaign IDs if other search conditions exclude them.
Note: Currently, only one campaign ID value is supported for each request.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "limit",
- "in": "query",
- "description": "The number of results, from the current result set, to be returned in a single page.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "negative_keyword_status",
- "in": "query",
- "description": "A comma-separated list of negative keyword statuses.
This query parameter is used if the seller wants to filter the search results based on one or more negative keyword statuses.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "The number of results that will be skipped in the result set. This is used with the limit field to control the pagination of the output.
For example, if the offset is set to 0 and the limit is set to 10, the method will retrieve items 1 through 10 from the list of items returned. If the offset is set to 10 and the limit is set to 10, the method will retrieve items 11 through 20 from the list of items returned.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/NegativeKeywordPagedCollectionResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35029": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
- },
- "35030": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'offset' cannot be less than zero."
- },
- "36329": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The ad group Id is required."
- },
- "36347": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Currently only one value is supported for 'campaign_ids'."
- },
- "36350": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'negative_keyword_status' is invalid."
- }
- }
- }
- },
- "403": {
- "description": "Forbidden"
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "post": {
- "tags": [
- "negative_keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method adds a negative keyword to an existing ad group in a PLA campaign that uses the Cost Per Click (CPC) funding model.
Specify the campaignId and adGroupId in the request body, along with the negativeKeywordText and negativeKeywordMatchType.
Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller.",
- "operationId": "createNegativeKeyword",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "A type that defines the fields for the request to create a negative keyword.",
- "content": {
- "application/json": {
- "schema": {
- "description": "A type that defines the fields for the request to create a negative keyword.",
- "$ref": "#/components/schemas/CreateNegativeKeywordRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "201": {
- "description": "Created",
- "headers": {
- "Location": {
- "schema": {
- "type": "string",
- "description": "The location response header contains the URI of the newly created negative keyword. The URI includes the newly created negativeKeywordId, which you can use to reference the negative keyword."
- }
- }
- },
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35035": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The campaign with campaign id {campaign_id} has ended."
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for campaign id {campaign_id}."
- },
- "36210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No ad group found for ad group id {ad_group_id}."
- },
- "36219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The ad group with ad group id {ad_group_id} has been archived."
- },
- "36323": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' {negativeKeywordText} and 'negativeKeywordMatchType' {negativeKeywordMatchType} already exists for this Campaign."
- },
- "36330": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The provided negative keyword match type is not supported. Valid values are: {negativeKeywordMatchTypeValues}."
- },
- "36331": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' {negativeKeywordText} and 'negativeKeywordMatchType' {negativeKeywordMatchType} already exists for this Ad Group."
- },
- "36332": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' {negativeKeywordText} cannot be more than {maxNegativeKeywordTextLength} characters."
- },
- "36333": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' cannot be null or empty"
- },
- "36334": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' contains invalid characters {invalidCharacters}"
- },
- "36335": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You have exceeded the maximum number of negative keyword for an ad group. Only {maxSupportedNegativeKeywordNumber} Ids are supported per ad group."
- },
- "36336": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'negativeKeywordText' {negativeKeywordText} cannot have total number of words more than {maxWordsInNegativeKeyword} words."
- },
- "36345": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'campaignId' and 'adGroupId' are required."
- },
- "36346": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You have exceeded the maximum number of negative keyword for a campaign. Only {maxSupportedNegativeKeywordNumberCampaign} Ids are supported per campaign."
- }
- }
- }
- },
- "403": {
- "description": "Forbidden"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/negative_keyword/{negative_keyword_id}": {
- "get": {
- "tags": [
- "negative_keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method retrieves details on a specific negative keyword.
In the request, specify the negative_keyword_id as a path parameter.",
- "operationId": "getNegativeKeyword",
- "parameters": [
- {
- "name": "negative_keyword_id",
- "in": "path",
- "description": "The unique identifier for the negative keyword.
This value is returned in the Location response header from the createNegativeKeyword method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/NegativeKeyword"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "36340": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No negative keyword found for negative keyword id {negativeKeywordId}."
- }
- }
- }
- },
- "403": {
- "description": "Forbidden"
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "put": {
- "tags": [
- "negative_keyword"
- ],
- "description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method updates the status of an existing negative keyword.
Specify the negative_keyword_id as a path parameter, and specify the negativeKeywordStatus in the request body.",
- "operationId": "updateNegativeKeyword",
- "parameters": [
- {
- "name": "negative_keyword_id",
- "in": "path",
- "description": "The unique identifier for the negative keyword.
This value is returned in the Location response header from the createNegativeKeyword method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "A type that defines the fields for the request to update a negative keyword.",
- "content": {
- "application/json": {
- "schema": {
- "description": "A type that defines the fields for the request to update a negative keyword.",
- "$ref": "#/components/schemas/UpdateNegativeKeywordRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "204": {
- "description": "Success"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "36340": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No negative keyword found for negative keyword id {negativeKeywordId}."
- },
- "36342": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "NegativeKeywordStatus is missing or invalid. It is required for update."
- },
- "36343": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Negative keyword with negative keyword id {negativeKeywordId} is already archived and cannot be updated."
- }
- }
- }
- },
- "403": {
- "description": "Forbidden"
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business error",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_report/{report_id}": {
- "get": {
- "tags": [
- "ad_report"
- ],
- "description": "This call downloads the report as specified by the report_id path parameter.
Call createReportTask to schedule and generate a Promoted Listings report. All date values are returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).
Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
This ID is generated by eBay when you run a report task with a call to createReportTask. Get all the seller's report IDs by calling getReportTasks.
",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "text/tab-separated-values": {
- "schema": {
- "type": "object"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35110": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'report_id' {report_id} was not found. Correct the 'report_id' and try the call again."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_report_metadata": {
- "get": {
- "tags": [
- "ad_report_metadata"
- ],
- "description": "This call retrieves information that details the fields used in each of the Promoted Listings reports. Use the returned information to configure the different types of Promoted Listings reports.The request for this method does not use a payload or any URI parameters.
Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged.",
- "operationId": "getReportMetadata",
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ReportMetadatas"
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope"
- ]
- }
- ]
- }
- },
- "/ad_report_metadata/{report_type}": {
- "get": {
- "tags": [
- "ad_report_metadata"
- ],
- "description": "This call retrieves metadata that details the fields used by a specific Promoted Listings report type. Use the report_type path parameter to indicate metadata to retrieve.
This method does not use a request payload.
Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged.",
- "operationId": "getReportMetadataForReportType",
- "parameters": [
- {
- "name": "report_type",
- "in": "path",
- "description": "The name of the report type whose metadata you want to retrieve.
Tip: For details about available report types and their descriptions, refer to the ReportTypeEnum.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ReportMetadata"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35116": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Supplied 'report_type' not found. Valid values are: {supportedReportTypes}."
- }
- }
- }
- },
- "403": {
- "description": "Forbidden",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You are currently not authorized to access the Promoted Listings Advanced program. Please contact support"
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope"
- ]
- }
- ]
- }
- },
- "/ad_report_task": {
- "get": {
- "tags": [
- "ad_report_task"
- ],
- "description": "This method returns information on all the existing report tasks related to a seller. Use the report_task_statuses query parameter to control which reports to return. You can paginate the result set by specifying a limit, which dictates how many report tasks to return on each page of the response. Use the offset parameter to specify how many reports to skip in the result set before returning the first result.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Default: 10
Maximum: 500
",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "Specifies the number of report tasks to skip in the result set before returning the first report in the paginated response. Combine offset with the limit query parameter to control the reports returned in the response. For example, if you supply an offset of 0 and a limit of 10, the response contains the first 10 reports from the complete list of report tasks retrieved by the call. If offset is 10 and limit is 10, the first page of the response contains reports 11-20 from the complete result set.
Default: 0",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "report_task_statuses",
- "in": "query",
- "description": "This parameter filters the returned report tasks by their status. Supply a comma-separated list of the report statuses you want returned. The results are filtered to include only the report statuses you specify.
Note: The results might not include some report tasks if other search conditions exclude them.
Valid values:
PENDING
SUCCESS
FAILED",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ReportTaskPagedCollection"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35029": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
- },
- "35030": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'offset' cannot be less than zero {offset}."
- },
- "35109": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'report_task_statuses' {invalid_report_task_statuses} is invalid. Valid values are: {supportedReportTaskStatuses}."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "post": {
- "tags": [
- "ad_report_task"
- ],
- "description": "Note: Using multiple funding models in one report is deprecated. If multiple funding models are used, a Warning will be returned in a header. This functionality will be decommissioned on April 3, 2023. See API Deprecation Status for details.
This method creates a report task, which generates a Promoted Listings report based on the values specified in the call.
The report is generated based on the criteria you specify, including the report type, the report's dimensions and metrics, the report's start and end dates, the listings to include in the report, and more. Metrics are the quantitative measurements in the report while dimensions specify the attributes of the data included in the reports.
When creating a report task, you can specify the items you want included in the report. The items you specify, using either listingId or inventoryReference values, must be in a Promoted Listings campaign for them to be included in the report.
For details on the required and optional fields for each report type, see Promoted Listings reporting.
This call returns the URL to the report task in the Location response header, and the URL includes the report-task ID.
Reports often take time to generate and it's common for this call to return an HTTP status of 202, which indicates the report is being generated. Call getReportTasks (or getReportTask with the report-task ID) to determine the status of a Promoted Listings report. When a report is complete, eBay sets its status to SUCCESS and you can download it using the URL returned in the reportHref field of the getReportTask call. Report files are tab-separated value gzip files with a file extension of .tsv.gz.
Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged.
Note: This call fails if you don't submit all the required fields for the specified report type. Fields not supported by the specified report type are ignored. Call getReportMetadata to retrieve a list of the fields you need to configure for each Promoted Listings report type.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Important! The data threshold for a single report is currently 500,000 records; if this threshold is exceeded, the report will fail.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "The container for the fields that define the report task.",
- "content": {
- "application/json": {
- "schema": {
- "description": "The container for the fields that define the report task.",
- "$ref": "#/components/schemas/CreateReportTask"
- }
- }
- },
- "required": true
- },
- "responses": {
- "202": {
- "description": "Accepted"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35012": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'inventoryReferenceId' {inventoryReferenceId} is not valid."
- },
- "35013": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'listingId' {listingId} is not valid. Correct the 'listingId' and try the call again."
- },
- "35040": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'inventoryReferenceType' {inventoryReferenceType} is not supported."
- },
- "35041": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A 'marketplaceId' is required. Supported marketplaces are: {supportedMarketplaces}"
- },
- "35045": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "No campaign found for {campaignId}."
- },
- "35090": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "dateFrom and dateTo span exceeds maximum allowed. Only up to {maxDayRange} days are supported."
- },
- "35100": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Campaign ID is required for this call."
- },
- "35102": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The {date_key} date is required for this call."
- },
- "35103": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The date cannot be in future."
- },
- "35104": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The report start date {dateFrom} cannot be after the end date {dateTo}."
- },
- "35105": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The report 'dateFrom' {dateFrom} is out of range. Reports are limited up to {maxDays} days in the past."
- },
- "35106": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'dimensionKey' {dimensionKey} is not valid. To see the supported dimension keys for a report, use one of the 'Get Metadata' calls."
- },
- "35107": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'dimensionKey' {dimensionKey} is not supported for the 'reportType' {reportType}. To see the supported dimension keys for a report, use one of the 'Get Metadata' calls."
- },
- "35108": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'annotationKey' {annotationKey} is not supported for the 'dimensionKey' {dimensionKey}. To see the supported annotation and dimension keys for a report, use one of the 'Get Metadata' calls."
- },
- "35111": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'inventoryReferenceId' {inventoryReferenceId} is not valid."
- },
- "35113": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID is required for this call."
- },
- "35114": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'reportType' is invalid. Valid values are: {supportedReportTypes}."
- },
- "35115": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'metricKey' {metricKey} is not supported for the 'reportType' {reportType}. To see the supported metric keys for a report, use one of the 'Get Metadata' calls."
- },
- "35118": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'reportFormat' is missing or invalid. Valid values are: {supportedReportFormats}"
- },
- "35119": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The minimum set of 'dimensionKey' is not provided for the 'reportType' {reportType}. Minimum required dimensionKeys are: {minimumDimensionKeys}"
- },
- "35120": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one 'metricKey' must be provided for 'reportType' {reportType}. Valid metricKeys are: {supportedMetricKeys}"
- },
- "35121": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'fundingModel' is invalid. Valid values are: {supportedFundingModels}."
- },
- "35122": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The metric key is not supported for the funding model."
- },
- "35123": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'dimensionKey' {dimensionKey} is not valid for the 'fundingModel' {fundingModel}"
- },
- "35124": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Multiple funding models are not supported. Please use one of the following funding models: {supportedFundingModels}"
- },
- "35130": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'annotationKey' {annotationKey} is not supported for the 'fundingModel' {fundingModel}."
- }
- }
- }
- },
- "403": {
- "description": "Forbidden",
- "x-response-codes": {
- "errors": {
- "35089": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You are currently not authorized to access the Promoted Listings Advanced program. Please contact support"
- },
- "35091": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'additionalRecords' are supported only with COST_PER_CLICK FundingModel and non-performing data is applicable for account level reports with no Day level dimension. 'additionalRecords' are applicable for reportTypes {supportedReportTypes}"
- }
- }
- }
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "35051": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'marketplaceId' {marketplaceId} is not supported. Supported marketplaces are: {supportedMarketplaces}"
- },
- "35068": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of listing IDs. Only {maxSupportedListings} listings are supported per call."
- },
- "35101": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You have exceeded the maximum number of campaign IDs. Only {maxSupportedCampaigns} campaigns are supported per call."
- },
- "35112": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The maximum number {maxSupportedInventoryReferences} of inventory references has been exceeded."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server error",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/ad_report_task/{report_task_id}": {
- "get": {
- "tags": [
- "ad_report_task"
- ],
- "description": "This call returns the details of a specific Promoted Listings report task, as specified by the report_task_id path parameter. The report task includes the report criteria (such as the report dimensions, metrics, and included listing) and the report-generation rules (such as starting and ending dates for the specified report task).
Report-task IDs are generated by eBay when you call createReportTask. Get a complete list of a seller's report-task IDs by calling getReportTasks.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Report task IDs are generated by eBay when you call createReportTask. Get a complete list of a seller's report-task IDs by calling getReportTasks.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Unlike an item promotion, a markdown promotion does not require the buyer meet a \"threshold\" before the offer takes effect. With markdown promotions, all the buyer needs to do is purchase the item to receive the promotion benefit.
Important: There are some restrictions for which listings are available for price markdown promotions. For details, see Promotions Manager requirements and restrictions.
In addition, we recommend you list items at competitive prices before including them in your markdown promotions. For an extensive list of pricing recommendations, see the Growth tab in Seller Hub.
There are two ways to add items to markdown promotions:
- Key-based promotions select items using either the listing IDs or inventory reference IDs of the items you want to promote. Note that if you use inventory reference IDs, you must specify both the inventoryReferenceId and the associated inventoryReferenceType of the item(s) you want to include the promotion.
- Rule-based promotions select items using a list of eBay category IDs or seller Store category IDs. Rules can further constrain items in a promotion by minimum and maximum prices, brands, and item conditions.
New promotions must be created in either a DRAFT or a SCHEDULED state. Use the DRAFT state when you are initially creating a promotion and you want to be sure it's correctly configured before scheduling it to run. When you create a promotion, the promotion ID is returned in the Location response header. Use this ID to reference the promotion in subsequent requests (such as to schedule a promotion that's in a DRAFT state).
Tip: Refer to Promotions Manager in the Selling Integration Guide for details and examples showing how to create and manage seller promotions.
Markdown promotions are available on all eBay marketplaces. For more information, see Promotions Manager requirements and restrictions.
",
- "operationId": "createItemPriceMarkdownPromotion",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This type defines the fields that describe an item price markdown promotion.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the fields that describe an item price markdown promotion.",
- "$ref": "#/components/schemas/ItemPriceMarkdown"
- }
- }
- },
- "required": false
- },
- "responses": {
- "201": {
- "description": "Created",
- "headers": {
- "Location": {
- "schema": {
- "type": "string",
- "description": "The location response header contains the URL to the newly created item price markdown promotion. The URL includes the eBay-assigned promotionId, which you can use to reference the promotion."
- }
- }
- },
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "38226": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID must be numeric if you're using listingIds."
- },
- "38227": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID is invalid."
- },
- "38263": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}."
- },
- "38272": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This listing is not eligible for a promotion because it's an auction-style listing."
- },
- "38273": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing."
- },
- "38274": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You haven't included electronic payment method as a payment method. In order to make this listing eligible, update it to include electronic payment method."
- },
- "38275": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This SKU used in inventoryReferenceId matches an item that is part of a listing with variations. This SKU is only eligible if we add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label)."
- },
- "345112": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid Store category. Please refer to API documentation to source allowed values."
- },
- "345113": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid marketplace category ID. Please refer to API documentation for the supported values."
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "38218": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A valid entry is required for {fieldName}."
- },
- "38219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The start date and time must be earlier than the end date and time."
- },
- "38220": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The end date and time must be later than the current date and time."
- },
- "38228": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The amount value of '{fieldName}' contains decimals, only integers are supported."
- },
- "38229": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The start date and time should be later than the current date and time."
- },
- "38234": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "HTML is not allowed in the '{fieldName}' field."
- },
- "38235": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the '{fieldName}' field. For help, see the documentation for this call."
- },
- "38238": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountBenefit' data is missing, which is required by this call. For help, see the documentation for this call."
- },
- "38240": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
- },
- "38242": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'."
- },
- "38255": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion description exceeds the maximum length, which is {promoDescriptionLength}."
- },
- "38256": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion name exceeds the maximum length, which is {promoNameLength}."
- },
- "38261": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Promotions are currently limited to a maximum of {maxListingInclLimit} parent items, when entering item IDs or choosing from live inventory."
- },
- "38262": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can only include up to {maxSkuInclLimit} SKUs or custom labels in inventoryItems."
- },
- "38270": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The currency type does not match what is used for the Marketplace ID submitted."
- },
- "345056": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these field types: 'inventoryItems' or 'listingIds'."
- },
- "345057": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these fields: 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call."
- },
- "345058": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "When using multiple selectedInventoryDiscounts containers, each must have a unique percentageoffitems value. For help, see the documentation for this call."
- },
- "345059": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "If using percentageoffitems you can have between 1 and 10 selectedInventoryDiscounts containers. For help, see the documentation for this call."
- },
- "345060": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "If using amountoffitems you can only have selectedInventoryDiscounts container. For help, see the documentation for this call."
- },
- "345061": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The discount ID value is a read only value."
- },
- "345063": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Priority is not supported for the item_price_markdown calls."
- },
- "345110": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only one of Inventory Items, Listing IDs or Rules in the Inventory Criterion."
- },
- "345111": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify Rules when using the Inventory by Value Criterion."
- },
- "345114": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A Category scope is required for the Rule. Please refer to API documentation for allowed values."
- },
- "345115": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one Category is required. Please provide a valid input for this field and try again."
- },
- "345116": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only Marketplace categories or Store categories when creating Rules."
- },
- "345120": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid Item condition. Please refer to API documentation for allowed values."
- },
- "345121": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion."
- },
- "345122": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "category ids cannot be specified with the inventory of type any."
- },
- "345123": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "brands cannot be specified with inventory of type any or Store."
- },
- "345125": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify a child Marketplace Category ID when the parent Marketplace Category ID is already specified. Please refer to the API documentation to source allowed values."
- },
- "345126": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify a child Store Category ID when the parent Store Category ID is already specified. Please refer to the API documentation to source allowed values."
- }
- }
- }
- },
- "409": {
- "description": "Business Error",
- "x-response-codes": {
- "errors": {
- "38248": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'percentOffItem' value is invalid. For help, see the documentation for this call."
- },
- "38250": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'amountOffItem' value is invalid. For help, see the documentation for this call."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/item_price_markdown/{promotion_id}": {
- "get": {
- "tags": [
- "item_price_markdown"
- ],
- "description": "This method returns the complete details of the item price markdown promotion that's indicated by the promotion_id path parameter.
Call getPromotions to retrieve the IDs of a seller's promotions.",
- "operationId": "getItemPriceMarkdownPromotion",
- "parameters": [
- {
- "name": "promotion_id",
- "in": "path",
- "description": "This path parameter takes a concatenation of the ID of the promotion you want to get plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.
Example: 1********5@EBAY_US",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ItemPriceMarkdown"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38203": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Resource not found. Check the ID and try the call again."
- },
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "put": {
- "tags": [
- "item_price_markdown"
- ],
- "description": "This method updates the specified item price markdown promotion with the new configuration that you supply in the payload of the request. Specify the promotion you want to update using the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's promotions.
When updating a promotion, supply all the fields that you used to configure the original promotion (and not just the fields you are updating). eBay replaces the specified promotion with the values you supply in the update request and if you don't pass a field that currently has a value, the update request fails.
The parameters you are allowed to update with this request depend on the status of the promotion you're updating: - DRAFT or SCHEDULED promotions: You can update any of the parameters in these promotions that have not yet started to run, including the discountRules.
- RUNNING promotions: You can change the endDate and the item's inventory but you cannot change the promotional discount or the promotion's start date.
- ENDED promotions: Nothing can be changed.
",
- "operationId": "updateItemPriceMarkdownPromotion",
- "parameters": [
- {
- "name": "promotion_id",
- "in": "path",
- "description": "This path parameter takes a concatenation of the ID of the promotion you want to update plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.
Example: 1********5@EBAY_US",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This type defines the fields that describe an item price markdown promotion.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the fields that describe an item price markdown promotion.",
- "$ref": "#/components/schemas/ItemPriceMarkdown"
- }
- }
- },
- "required": false
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "38226": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID must be numeric if you're using listingIds."
- },
- "38227": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID is invalid."
- },
- "38263": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}."
- },
- "38272": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This listing is not eligible for a promotion because it's an auction-style listing."
- },
- "38273": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing."
- },
- "38274": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You haven't included electronic payment method as a payment method. In order to make this listing eligible, update it to include electronic payment method."
- },
- "38275": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This SKU used in inventoryReferenceId matches an item that is part of a listing with variations. This SKU is only eligible if we add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label)."
- },
- "345064": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You have moved inventory between discountBenefit containers or have the same inventory in multiple discountBenefit containers. For help, see the documentation for this call."
- },
- "345112": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid Store category. Please refer to API documentation to source allowed values."
- },
- "345113": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid marketplace category ID. Please refer to API documentation for the supported values."
- }
- }
- }
- },
- "204": {
- "description": "Success"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38203": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Resource not found. Check the ID and try the call again."
- },
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "38218": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A valid entry is required for {fieldName}."
- },
- "38219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The start date and time must be earlier than the end date and time."
- },
- "38220": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The end date and time must be later than the current date and time."
- },
- "38225": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update a promotion that has ended."
- },
- "38228": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The amount value of '{fieldName}' contains decimals, only integers are supported."
- },
- "38229": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The start date and time should be later than the current date and time."
- },
- "38232": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update the promotion discount for an active promotion."
- },
- "38234": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "HTML is not allowed in the '{fieldName}' field."
- },
- "38235": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the '{fieldName}' field. For help, see the documentation for this call."
- },
- "38238": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountBenefit' data is missing, which is required by this call. For help, see the documentation for this call."
- },
- "38240": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
- },
- "38242": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'."
- },
- "38255": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion description exceeds the maximum length, which is {promoDescriptionLength}."
- },
- "38256": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion name exceeds the maximum length, which is {promoNameLength}."
- },
- "38260": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "To update the start date of a promotion, the promotion must be in draft or scheduled state."
- },
- "38261": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Promotions are currently limited to a maximum of {maxListingInclLimit} parent items, when entering item IDs or choosing from live inventory."
- },
- "38262": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can only include up to {maxSkuInclLimit} SKUs or custom labels in inventoryItems."
- },
- "38269": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion ID does not match any of the seller's promotions."
- },
- "38270": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The currency type does not match what is used for the Marketplace ID submitted."
- },
- "345056": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these field types: 'inventoryItems' or 'listingIds'."
- },
- "345057": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these fields: 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call."
- },
- "345058": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "When using multiple selectedInventoryDiscounts containers, each must have a unique percentageoffitems value. For help, see the documentation for this call."
- },
- "345059": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "If using percentageoffitems you can have between 1 and 10 selectedInventoryDiscounts containers. For help, see the documentation for this call."
- },
- "345060": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "If using amountoffitems you can only have selectedInventoryDiscounts container. For help, see the documentation for this call."
- },
- "345061": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The discount ID value is a read only value."
- },
- "345063": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Priority is not supported for the item_price_markdown calls."
- },
- "345065": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot change the status of aa SCHEDULED promotion to DRAFT. For help, see the documentation for this call."
- },
- "345070": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The giving discount ID does not exist in the promotion. For help, see the documentation for this call."
- },
- "345071": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The giving discount type is not consistent with existing active promotion. For help, see the documentation for this call."
- },
- "345072": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The giving inventory criterion type is not consistent with existing active promotion. For help, see the documentation for this call."
- },
- "345110": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only one of Inventory Items, Listing IDs or Rules in the Inventory Criterion."
- },
- "345111": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify Rules when using the Inventory by Value Criterion."
- },
- "345114": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A Category scope is required for the Rule. Please refer to API documentation for allowed values."
- },
- "345115": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one Category is required. Please provide a valid input for this field and try again."
- },
- "345116": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only Marketplace categories or Store categories when creating Rules."
- },
- "345120": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid Item condition. Please refer to API documentation for allowed values."
- },
- "345121": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify Rules or inventory items when using the Inventory by ALL Criterion."
- },
- "345122": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "category ids cannot be specified with the inventory of type any."
- },
- "345123": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "brands cannot be specified with inventory of type any or Store."
- },
- "345125": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify a child Marketplace Category ID when the parent Marketplace Category ID is already specified. Please refer to the API documentation to source allowed values."
- },
- "345126": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify a child Store Category ID when the parent Store Category ID is already specified. Please refer to the API documentation to source allowed values."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business Error",
- "x-response-codes": {
- "errors": {
- "38248": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'percentOffItem' value is invalid. For help, see the documentation for this call."
- },
- "38250": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'amountOffItem' value is invalid. For help, see the documentation for this call."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, please contact support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "delete": {
- "tags": [
- "item_price_markdown"
- ],
- "description": "This method deletes the item price markdown promotion specified by the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's promotions.
You can delete any promotion with the exception of those that are currently active (RUNNING). To end a running promotion, call updateItemPriceMarkdownPromotion and adjust the endDate field as appropriate.",
- "operationId": "deleteItemPriceMarkdownPromotion",
- "parameters": [
- {
- "name": "promotion_id",
- "in": "path",
- "description": "This path parameter takes a concatenation of the ID of the promotion you want to delete plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.
Example: 1********5@EBAY_US",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38203": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Resource not found. Check the ID and try the call again."
- },
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "345067": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A promotion can only be deleted if it is ended."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, please contact support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/item_promotion": {
- "post": {
- "tags": [
- "item_promotion"
- ],
- "description": "This method creates an item promotion, where the buyer receives a discount when they meet the buying criteria that's set for the promotion. Known here as \"threshold promotions\", these promotions trigger when a threshold is met. eBay highlights promoted items by placing teasers for the promoted items throughout the online buyer flows.
Discounts are specified as either a monetary amount or a percentage off the standard sales price of a listing, letting you offer deals such as \"Buy 1 Get 1\" and \"Buy $50, get 20% off\".
Volume pricing promotions increase the value of the discount as the buyer increases the quantity they purchase.
Coded Coupons provide unique codes that a buyer can use during checkout to receive a discount. The seller can specify the number of times a buyer can use the coupon and the maximum amount across all purchases that can be discounted using the coupon. The coupon code can also be made public (appearing on the seller's Offer page, search pages, the item listing, and the checkout page) or private (only on the seller's Offer page, but the seller can include the code in email and social media).
Note: Coded Coupons are currently available in the US, UK, DE, FR, IT, ES, and AU marketplaces.
There are two ways to add items to a threshold promotion:
- Key-based promotions select items using either the listing IDs or inventory reference IDs of the items you want to promote. Note that if you use inventory reference IDs, you must specify both the inventoryReferenceId and the associated inventoryReferenceType of the item(s) you want to include the promotion.
- Rule-based promotions select items using a list of eBay category IDs or seller Store category IDs. Rules can further constrain items in a promotion by minimum and maximum prices, brands, and item conditions.
You must create a new promotion in either a DRAFT or SCHEDULED state. Use the DRAFT state when you are initially creating a promotion and you want to be sure it's correctly configured before scheduling it to run. When you create a promotion, the promotion ID is returned in the Location response header. Use this ID to reference the promotion in subsequent requests.
Tip: Refer to the Selling Integration Guide for details and examples showing how to create and manage threshold promotions using the Promotions Manager.
For information on the eBay marketplaces that support item promotions, see Promotions Manager requirements and restrictions.
",
- "operationId": "createItemPromotion",
- "parameters": [
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This type defines the fields that describe an item promotion.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the fields that describe an item promotion.",
- "$ref": "#/components/schemas/ItemPromotion"
- }
- }
- },
- "required": false
- },
- "responses": {
- "201": {
- "description": "Created",
- "headers": {
- "Location": {
- "schema": {
- "type": "string",
- "description": "URL location of new item promotion."
- }
- }
- },
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BaseResponse"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "38226": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID must be numeric if you're using listingIds."
- },
- "38227": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID is invalid."
- },
- "38263": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}."
- },
- "38272": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This listing is not eligible for a promotion because it's an auction-style listing."
- },
- "38273": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing."
- },
- "38274": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You haven't included electronic payment method as a payment method. In order to make this listing eligible, update it to include electronic payment method."
- },
- "38275": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This SKU used in inventoryReferenceId matches an item that is part of a listing with variations. This SKU is only eligible if you add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label)."
- },
- "345112": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid Store category. Please refer to API documentation to source allowed values."
- },
- "345113": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid marketplace category ID. Please refer to API documentation for the supported values."
- },
- "345137": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'priority' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345138": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'description' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345139": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'applyDiscountToSingleItemOnly' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345140": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'promotionImageUrl' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345142": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'applyDiscountToSingleItemOnly' is currently not supported for this Marketplace ID. For help, see the documentation for this call."
- },
- "345143": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'couponType' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345144": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'maxCouponRedemptionPerUser' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345145": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'maxDiscountAmount' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345146": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'budget' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345147": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'couponCode' can not be set for this promotion type. For help, see the documentation for this call."
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "38205": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The Marketplace ID is not recognized or is not eligible for promotions."
- },
- "38207": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion priority is invalid. Please check and try the call again."
- },
- "38218": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A valid entry is required for {fieldName}."
- },
- "38219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Zonks! The start date and time must be earlier than the end date and time."
- },
- "38220": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The end date and time must be later than the current date and time."
- },
- "38228": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The amount value of '{fieldName}' contains decimals, only integers are supported."
- },
- "38229": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The start date and time should be later than the current date and time."
- },
- "38234": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "HTML is not allowed in the '{fieldName}' field."
- },
- "38235": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the '{fieldName}' field. For help, see the documentation for this call."
- },
- "38236": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountSpecification' data is missing, which is required by this call. For help, see the documentation for this call."
- },
- "38237": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these fields: 'minQuantity', 'forEachQuantity', 'minAmount', or 'forEachAmount' in 'discountSpecification'. For help, see the documentation for this call."
- },
- "38238": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountBenefit' data is missing, which is required by this call. For help, see the documentation for this call."
- },
- "38239": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these fields: 'percentageOffOrder', 'amountOffOrder', 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call."
- },
- "38240": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
- },
- "38241": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This discount rule combination is currently not supported. For help, see the documentation for this call."
- },
- "38242": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'."
- },
- "38253": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The data combination of 'DiscountSpecification' and 'DiscountBenefit' is not valid for this promotion type. For help, see the documentation for this call."
- },
- "38255": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion description exceeds the maximum length, which is {promoDescriptionLength}."
- },
- "38256": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion name exceeds the maximum length, which is {promoNameLength}."
- },
- "38257": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This promotion type supports only one discount rule for the item promotion."
- },
- "38260": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "To update the start date of a promotion, the promotion must be in draft or scheduled state."
- },
- "38261": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Promotions are currently limited to a maximum of {maxListingInclLimit} parent items, when entering item IDs or choosing from live inventory."
- },
- "38262": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can only include up to {maxSkuInclLimit} SKUs or custom labels in inventoryItems."
- },
- "38265": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Number of discount items is greater than the quantity specified in 'DiscountSpecification'."
- },
- "38267": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'DiscountBenefit.amountOffOrder' field cannot be used with the 'DiscountSpecification.numberOfDiscountedItems' field. This parameter is reserved for Buy x, Get x discounts. For help, see the documentation for this call."
- },
- "345110": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only one of Inventory Items, Listing IDs or Rules in the Inventory Criterion."
- },
- "345111": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify Rules when using the Inventory by Value Criterion."
- },
- "345114": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A Category scope is required for the Rule. Please refer to API documentation for allowed values."
- },
- "345115": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one Category is required. Please provide a valid input for this field and try again."
- },
- "345116": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only Marketplace categories or Store categories when creating Rules."
- },
- "345118": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion."
- },
- "345120": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid Item condition. Please refer to API documentation for allowed values."
- },
- "345121": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion."
- },
- "345122": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "category ids cannot be specified with the inventory of type any."
- },
- "345123": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "brands cannot be specified with inventory of type any or Store."
- },
- "345124": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Exclusions are currently limited to a maximum of 100 parent items, when entering Inventory Items or Listing IDs, or choosing from live inventory."
- },
- "345125": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify a child Marketplace Category ID when the parent Marketplace Category ID is already specified. Please refer to the API documentation to source allowed values."
- },
- "345126": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify a child Store Category ID when the parent Store Category ID is already specified. Please refer to the API documentation to source allowed values."
- },
- "345127": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Category aspects are not supported in this version."
- },
- "345128": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The minimum discount rules required for volume discount promotions are {numOfDiscountRules}"
- },
- "345129": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountRules.ruleOrder' is missing or invalid for one of the discount rules for volume discount promotions. see the documentation for this call."
- },
- "345130": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can include up to a maximum of {numOfDiscountRules} discount rules in a volume discount promotion."
- },
- "345131": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Each 'minQuantity' value should be one greater than the 'minQuantity' value of the previous discount rule."
- },
- "345132": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The discount value is invalid for one of the discount rules for volume discount promotions. see the documentation for this call."
- },
- "345133": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Each 'percentageOffOrder' or 'amountOffOrder' value should be greater than the 'percentageOffOrder' or 'amountOffOrder' value of the previous discount rule for volume discount promotions."
- },
- "345134": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This promotionType is currently not supported. For help, see the documentation for this call."
- },
- "345136": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountBenefit' specified is not supported for this promotion Type. For help, see the documentation for this call."
- },
- "345137": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'couponCode' data is missing for coded coupon promotions. For help, see the documentation for this call."
- },
- "345138": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'couponCode' value is invalid. For help, see the documentation for this call."
- },
- "345139": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'couponType' data is missing for coded coupon promotions. For help, see the documentation for this call."
- },
- "345140": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'couponType' value is invalid. For help, see the documentation for this call."
- },
- "345141": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'maxDiscountAmount' data is missing for coded coupon promotions. For help, see the documentation for this call."
- },
- "345142": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'maxDiscountAmount' value is invalid. For help, see the documentation for this call."
- },
- "345143": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'maxCouponRedemptionPerUser' value is invalid. For help, see the documentation for this call."
- },
- "345144": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'budget' value is invalid. For help, see the documentation for this call."
- },
- "345145": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A coupon with this 'couponCode' already exists. Please try a different 'couponCode'."
- },
- "345146": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'currency' for 'maxDiscountAmount' and 'budget' has to be same. For help, see the documentation for this call."
- },
- "345147": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'promotionType' CODED_COUPON is currently not supported for this Marketplace ID. For help, see the documentation for this call."
- },
- "345148": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountBenefit' value cannot exceed the 'maxDiscountAmount' value."
- }
- }
- }
- },
- "409": {
- "description": "Conflict",
- "x-response-codes": {
- "errors": {
- "38243": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'minQuantity' value is invalid. This value must be an integer."
- },
- "38244": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'forEachQuantity' value is invalid. This value must be an integer."
- },
- "38245": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'minAmount' value is invalid. For help, see the documentation for this call."
- },
- "38246": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'forEachAmount' value is invalid. For help, see the documentation for this call."
- },
- "38247": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'numberOfDiscountedItems' value is invalid. This value must be an integer."
- },
- "38248": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'percentOffItem' value is invalid. For help, see the documentation for this call."
- },
- "38249": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'percentOffOrder' value is invalid. For help, see the documentation for this call."
- },
- "38250": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'amountOffItem' value is invalid. For help, see the documentation for this call."
- },
- "38251": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'amountOffOrder' value is invalid. For help, see the documentation for this call."
- },
- "38266": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification.maxAmount' value."
- },
- "38268": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification'."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/item_promotion/{promotion_id}": {
- "get": {
- "tags": [
- "item_promotion"
- ],
- "description": "This method returns the complete details of the threshold promotion specified by the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's promotions.",
- "operationId": "getItemPromotion",
- "parameters": [
- {
- "name": "promotion_id",
- "in": "path",
- "description": "This path parameter takes a concatenation of the ID of the promotion you want to retrieve plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.
Example: 1********5@EBAY_US",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ItemPromotionResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38203": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Resource not found. Check the ID and try the call again."
- },
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "345076": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot get the details of a promotion that was not created through the API."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "put": {
- "tags": [
- "item_promotion"
- ],
- "description": "This method updates the specified threshold promotion with the new configuration that you supply in the request. Indicate the promotion you want to update using the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's promotions.
When updating a promotion, supply all the fields that you used to configure the original promotion (and not just the fields you are updating). eBay replaces the specified promotion with the values you supply in the update request and if you don't pass a field that currently has a value, the update request will fail.
The parameters you are allowed to update with this request depend on the status of the promotion you're updating:
- DRAFT or SCHEDULED promotions: You can update any of the parameters in these promotions that have not yet started to run, including the discountRules.
- RUNNING or PAUSED promotions: You can change the endDate and the item's inventory but you cannot change the promotional discount or the promotion's start date.
- ENDED promotions: Nothing can be changed.
Tip: When updating a RUNNING or PAUSED promotion, set the status field to SCHEDULED for the update request. When the promotion is updated, the previous status (either RUNNING or PAUSED) is retained.
",
- "operationId": "updateItemPromotion",
- "parameters": [
- {
- "name": "promotion_id",
- "in": "path",
- "description": "This path parameter takes a concatenation of the ID of the promotion you want to update plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.
Example: 1********5@EBAY_US",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "This type defines the fields that describe an item promotion.",
- "content": {
- "application/json": {
- "schema": {
- "description": "This type defines the fields that describe an item promotion.",
- "$ref": "#/components/schemas/ItemPromotion"
- }
- }
- },
- "required": false
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/BaseResponse"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "38226": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID must be numeric if you're using listingIds."
- },
- "38227": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The listing ID is invalid."
- },
- "38263": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}."
- },
- "38272": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This listing is not eligible for a promotion because it's an auction-style listing."
- },
- "38273": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing."
- },
- "38274": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "You haven't included electronic payment method as a payment method. In order to make this listing eligible, update it to include electronic payment method ."
- },
- "38275": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "This SKU used in inventoryReferenceId matches an item that is part of a listing with variations. This SKU is only eligible if you add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label)."
- },
- "345112": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid Store category. Please refer to API documentation to source allowed values."
- },
- "345113": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid marketplace category ID. Please refer to API documentation for the supported values."
- },
- "345137": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'priority' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345138": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'description' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345139": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'applyDiscountToSingleItemOnly' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345140": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'promotionImageUrl' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345142": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'applyDiscountToSingleItemOnly' is currently not supported for this Marketplace ID. For help, see the documentation for this call."
- },
- "345143": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'couponType' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345144": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'maxCouponRedemptionPerUser' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345145": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'maxDiscountAmount' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345146": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'budget' can not be set for this promotion type. For help, see the documentation for this call."
- },
- "345147": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'couponCode' can not be set for this promotion type. For help, see the documentation for this call."
- }
- }
- }
- },
- "204": {
- "description": "Success"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38203": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Resource not found. Check the ID and try the call again."
- },
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "38207": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion priority is invalid. Please check and try the call again."
- },
- "38210": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot change the priority of a promotion that is ended or deleted."
- },
- "38218": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A valid entry is required for {fieldName}."
- },
- "38219": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The start date and time must be earlier than the end date and time."
- },
- "38220": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The end date and time must be later than the current date and time."
- },
- "38225": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update a promotion that has ended."
- },
- "38228": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The amount value of '{fieldName}' contains decimals, only integers are supported."
- },
- "38229": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The start date and time should be later than the current date and time."
- },
- "38232": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update the promotion discount for an active promotion."
- },
- "38234": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "HTML is not allowed in the '{fieldName}' field."
- },
- "38235": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the '{fieldName}' field. For help, see the documentation for this call."
- },
- "38236": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountSpecification' data is missing, which is required by this call. For help, see the documentation for this call."
- },
- "38237": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these fields: 'minQuantity', 'forEachQuantity', 'minAmount', or 'forEachAmount' in 'discountSpecification'. For help, see the documentation for this call."
- },
- "38238": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountBenefit' data is missing, which is required by this call. For help, see the documentation for this call."
- },
- "38239": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these fields: 'percentageOffOrder', 'amountOffOrder', 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call."
- },
- "38240": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
- },
- "38241": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This discount rule combination is currently not supported. For help, see the documentation for this call."
- },
- "38242": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'."
- },
- "38253": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The data combination of 'DiscountSpecification' and 'DiscountBenefit' is not valid for this promotion type. For help, see the documentation for this call."
- },
- "38255": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion description exceeds the maximum length, which is {promoDescriptionLength}."
- },
- "38256": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion name exceeds the maximum length, which is {promoNameLength}."
- },
- "38257": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This promotion type supports only one discount rule for the item promotion."
- },
- "38260": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "To update the start date of a promotion, the promotion must be in draft or scheduled state."
- },
- "38261": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Promotions are currently limited to a maximum of {maxListingInclLimit} parent items, when entering item IDs or choosing from live inventory."
- },
- "38262": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can only include up to {maxSkuInclLimit} SKUs or custom labels in inventoryItems."
- },
- "38265": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Number of discount items is greater than the quantity specified in 'DiscountSpecification'."
- },
- "38267": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'DiscountBenefit.amountOffOrder' field cannot be used with the 'DiscountSpecification.numberOfDiscountedItems' field. This parameter is reserved for Buy x, Get x discounts. For help, see the documentation for this call."
- },
- "38269": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The promotion ID does not match any of the seller's promotions."
- },
- "38270": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The currency type does not match what is used for the Marketplace ID submitted."
- },
- "38271": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Only new or scheduled promotions can be saved as a draft."
- },
- "345077": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update a promotion that was not created through the API."
- },
- "345110": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only one of Inventory Items, Listing IDs or Rules in the Inventory Criterion."
- },
- "345111": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify Rules when using the Inventory by Value Criterion."
- },
- "345114": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A Category scope is required for the Rule. Please refer to API documentation for allowed values."
- },
- "345115": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "At least one Category is required. Please provide a valid input for this field and try again."
- },
- "345116": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only Marketplace categories or Store categories when creating Rules."
- },
- "345118": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion."
- },
- "345120": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid Item condition. Please refer to API documentation for allowed values."
- },
- "345121": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify Rules or inventory items when using the Inventory by ALL Criterion."
- },
- "345122": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "category ids cannot be specified with the inventory of type any."
- },
- "345123": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "brands cannot be specified with inventory of type any or Store."
- },
- "345124": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Exclusions are currently limited to a maximum of 100 parent items, when entering Inventory Items or Listing IDs, or choosing from live inventory."
- },
- "345125": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify a child Marketplace Category ID when the parent Marketplace Category ID is already specified. Please refer to the API documentation to source allowed values."
- },
- "345126": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot specify a child Store Category ID when the parent Store Category ID is already specified. Please refer to the API documentation to source allowed values."
- },
- "345127": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Category aspects are not supported in this version."
- },
- "345128": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The minimum discount rules required for volume discount promotions are {numOfDiscountRules}"
- },
- "345129": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountRules.ruleOrder' is missing or invalid for one of the discount rules for volume discount promotions. see the documentation for this call."
- },
- "345130": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can include up to a maximum of {numOfDiscountRules} discount rules in a volume discount promotion."
- },
- "345131": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Each 'minQuantity' value should be one greater than the 'minQuantity' value of the previous discount rule."
- },
- "345132": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The discount value is invalid for one of the discount rules for volume discount promotions. see the documentation for this call."
- },
- "345133": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Each 'percentageOffOrder' or 'amountOffOrder' value should be greater than the 'percentageOffOrder' or 'amountOffOrder' value of the previous discount rule for volume discount promotions."
- },
- "345134": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "This promotionType is currently not supported. For help, see the documentation for this call."
- },
- "345135": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update the promotion type for a promotion."
- },
- "345136": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountBenefit' specified is not supported for this promotion Type. For help, see the documentation for this call."
- },
- "345137": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'couponCode' value is invalid. For help, see the documentation for this call."
- },
- "345138": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update the 'couponCode' for an active or paused promotion."
- },
- "345139": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'couponType' data is invalid. For help, see the documentation for this call."
- },
- "345140": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update the 'couponType' for an active or paused promotion."
- },
- "345141": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'maxCouponRedemptionPerUser' value is invalid. For help, see the documentation for this call."
- },
- "345142": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update the 'maxCouponRedemptionPerUser' for an active or paused promotion."
- },
- "345143": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'maxDiscountAmount' value is invalid. For help, see the documentation for this call.\n"
- },
- "345144": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update the 'maxDiscountAmount' for an active or paused promotion."
- },
- "345145": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot apply a 'budget' to an active or paused promotion. For help, see the documentation for this call."
- },
- "345146": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'budget' value is invalid. For help, see the documentation for this call."
- },
- "345147": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'budget' value cannot be decreased. For help, see the documentation for this call."
- },
- "345148": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A coupon with this 'couponCode' already exists. Please try a different 'couponCode'."
- },
- "345149": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'currency' for 'maxDiscountAmount' and 'budget' has to be same. For help, see the documentation for this call."
- },
- "345150": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "'promotionType' CODED_COUPON is currently not supported for this Marketplace ID. For help, see the documentation for this call."
- },
- "345151": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'discountBenefit' value cannot exceed the 'maxDiscountAmount' value."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "409": {
- "description": "Business Error",
- "x-response-codes": {
- "errors": {
- "38243": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'minQuantity' value is invalid. This value must be an integer."
- },
- "38244": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'forEachQuantity' value is invalid. This value must be an integer."
- },
- "38245": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'minAmount' value is invalid. For help, see the documentation for this call."
- },
- "38246": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'forEachAmount' value is invalid. For help, see the documentation for this call."
- },
- "38247": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'numberOfDiscountedItems' value is invalid. This value must be an integer."
- },
- "38248": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'percentOffItem' value is invalid. For help, see the documentation for this call."
- },
- "38249": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'percentOffOrder' value is invalid. For help, see the documentation for this call."
- },
- "38250": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'amountOffItem' value is invalid. For help, see the documentation for this call."
- },
- "38251": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'amountOffOrder' value is invalid. For help, see the documentation for this call."
- },
- "38266": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification.maxAmount' value."
- },
- "38268": {
- "domain": "API_MARKETING",
- "category": "BUSINESS",
- "description": "The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification'."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, please contact support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "delete": {
- "tags": [
- "item_promotion"
- ],
- "description": "This method deletes the threshold promotion specified by the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's promotions.
You can delete any promotion with the exception of those that are currently active (RUNNING). To end a running threshold promotion, call updateItemPromotion and adjust the endDate field as appropriate.",
- "operationId": "deleteItemPromotion",
- "parameters": [
- {
- "name": "promotion_id",
- "in": "path",
- "description": "This path parameter takes a concatenation of the ID of the promotion you want to delete plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.
Example: 1********5@EBAY_US",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "No Content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38203": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Resource not found. Check the ID and try the call again."
- },
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "38216": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A promotion can only be deleted if it is paused or ended."
- },
- "345077": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update a promotion that was not created through the API."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, please contact support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/promotion/{promotion_id}/get_listing_set": {
- "get": {
- "tags": [
- "promotion"
- ],
- "description": "This method returns the set of listings associated with the promotion_id specified in the path parameter. Call getPromotions to retrieve the IDs of a seller's promotions. The listing details are returned in a paginated set and you can control and results returned using the following query parameters: limit, offset, q, sort, and status.
- Maximum associated listings returned: 200
- Default number of listings returned: 200
",
- "operationId": "getListingSet",
- "parameters": [
- {
- "name": "limit",
- "in": "query",
- "description": "Specifies the maximum number of promotions returned on a page from the result set.
Default: 200
Maximum: 200",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "Specifies the number of promotions to skip in the result set before returning the first promotion in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "promotion_id",
- "in": "path",
- "description": "This path parameter takes a concatenation of the ID of the promotion you want to get plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.
Example: 1********5@EBAY_US",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "q",
- "in": "query",
- "description": "Reserved for future use.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "sort",
- "in": "query",
- "description": "Specifies the order in which to sort the associated listings in the response. If you precede the supplied value with a dash, the response is sorted in reverse order.
Example:
sort=PRICE - Sorts the associated listings by their current price in ascending order
sort=-TITLE - Sorts the associated listings by their title in descending alphabetical order (Z-Az-a)
Valid values: For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/marketing/types/csb:SortField",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "status",
- "in": "query",
- "description": "This query parameter applies only to markdown promotions. It filters the response based on the indicated status of the promotion. Currently, the only supported value for this parameter is MARKED_DOWN, which indicates active markdown promotions. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/marketing/types/sme:ItemMarkdownStatusEnum",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ItemsPagedCollection"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "345062": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Sort is not supported for this promotion type. For help, see the documentation for this call."
- },
- "345068": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The value of the 'Status' parameter is invalid. For help, see the documentation for this call."
- },
- "345069": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The 'Status' parameter is only supported for itemPriceMarkdownPromotions. For help, see the documentation for this call."
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38203": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Resource not found. Check the ID and try the call again."
- },
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "38211": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The offset value must be an integer value greater than or equal to zero."
- },
- "38212": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The sort value was not valid. For the valid values, see the documentation for this call."
- },
- "38213": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can query a limit of between 0 and 200 promotion records at a time. Update the request and resubmit the call."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/promotion": {
- "get": {
- "tags": [
- "promotion"
- ],
- "description": "This method returns a list of a seller's undeleted promotions. The call returns up to 200 currently-available promotions on the specified marketplace. While the response body does not include the promotion's discountRules or inventoryCriterion containers, it does include the promotionHref (which you can use to retrieve the complete details of the promotion).
Use query parameters to sort and filter the results by the number of promotions to return, the promotion state or type, and the eBay marketplace. You can also supply keywords to limit the response to the promotions that contain that keywords in the title of the promotion.
Maximum returned: 200
",
- "operationId": "getPromotions",
- "parameters": [
- {
- "name": "limit",
- "in": "query",
- "description": "Specifies the maximum number of promotions returned on a page from the result set.
Default: 200
Maximum: 200",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "marketplace_id",
- "in": "query",
- "description": "The eBay marketplace ID of the site where the promotion is hosted. Valid values:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "Specifies the number of promotions to skip in the result set before returning the first promotion in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "promotion_status",
- "in": "query",
- "description": "Specifies the promotion state by which you want to filter the results. The response contains only those promotions that match the state you specify.
Valid values: DRAFTSCHEDULEDRUNNINGPAUSEDENDED
Maximum number of input values: 1",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "promotion_type",
- "in": "query",
- "description": "Filters the returned promotions based on their campaign promotion type. Specify one of the following values to indicate the promotion type you want returned: CODED_COUPON – A coupon code promotion set with createItemPromotion.MARKDOWN_SALE – A markdown promotion set with createItemPriceMarkdownPromotion.ORDER_DISCOUNT – A threshold promotion set with createItemPromotion.VOLUME_DISCOUNT – A volume pricing promotion set with createItemPromotion.
",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "q",
- "in": "query",
- "description": "A string consisting of one or more keywords. eBay filters the response by returning only the promotions that contain the supplied keywords in the promotion title.
Example: \"iPhone\" or \"Harry Potter.\"
Commas that separate keywords are ignored. For example, a keyword string of \"iPhone, iPad\" equals \"iPhone iPad\", and each results in a response that contains promotions with both \"iPhone\" and \"iPad\" in the title.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "sort",
- "in": "query",
- "description": "Specifies the order for how to sort the response. If you precede the supplied value with a dash, the response is sorted in reverse order.
Example:
sort=END_DATE Sorts the promotions in the response by their end dates in ascending order
sort=-PROMOTION_NAME Sorts the promotions by their promotion name in descending alphabetical order (Z-Az-a)
Valid values:START_DATEEND_DATEPROMOTION_NAME
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/marketing/types/csb:SortField",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/PromotionsPagedCollection"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "38211": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The offset value must be an integer value greater than or equal to zero."
- },
- "38212": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The sort value was not valid. For the valid values, see the documentation for this call."
- },
- "38213": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can query a limit of between 0 and 200 promotion records at a time. Update the request and resubmit the call."
- },
- "38240": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
- },
- "345141": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the 'promotionType' field. For help, see the documentation for this call."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/promotion/{promotion_id}/pause": {
- "post": {
- "tags": [
- "promotion"
- ],
- "description": "This method pauses a currently-active (RUNNING) threshold promotion and changes the state of the promotion from RUNNING to PAUSED. Pausing a promotion makes the promotion temporarily unavailable to buyers and any currently-incomplete transactions will not receive the promotional offer until the promotion is resumed. Also, promotion teasers are not displayed when a promotion is paused.
Pass the ID of the promotion you want to pause using the promotion_id path parameter. Call getPromotions to retrieve the IDs of the seller's promotions.
Note: You can only pause threshold promotions (you cannot pause markdown promotions).",
- "operationId": "pausePromotion",
- "parameters": [
- {
- "name": "promotion_id",
- "in": "path",
- "description": "This path parameter takes a concatenation of the ID of the promotion you want to pause plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.
Example: 1********5@EBAY_US",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "Success"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38203": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Resource not found. Check the ID and try the call again."
- },
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "38214": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "A promotion can only be paused if it is scheduled or running."
- },
- "345077": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update a promotion that was not created through the API."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/promotion/{promotion_id}/resume": {
- "post": {
- "tags": [
- "promotion"
- ],
- "description": "This method restarts a threshold promotion that was previously paused and changes the state of the promotion from PAUSED to RUNNING. Only promotions that have been previously paused can be resumed. Resuming a promotion reinstates the promotional teasers and any transactions that were in motion before the promotion was paused will again be eligible for the promotion.
Pass the ID of the promotion you want to resume using the promotion_id path parameter. Call getPromotions to retrieve the IDs of the seller's promotions.",
- "operationId": "resumePromotion",
- "parameters": [
- {
- "name": "promotion_id",
- "in": "path",
- "description": "This path parameter takes a concatenation of the ID of the promotion you want to resume plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an \"at sign\" (@).
The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.
Example: 1********5@EBAY_US",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "Success"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38203": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Resource not found. Check the ID and try the call again."
- },
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "38209": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot resume a promotion that is not paused or has already ended."
- },
- "345077": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You cannot update a promotion that was not created through the API."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/promotion_report": {
- "get": {
- "tags": [
- "promotion_report"
- ],
- "description": "This method generates a report that lists the seller's running, paused, and ended promotions for the specified eBay marketplace. The result set can be filtered by the promotion status and the number of results to return. You can also supply keywords to limit the report to promotions that contain the specified keywords.
Specify the eBay marketplace for which you want the report run using the marketplace_id query parameter. Supply additional query parameters to control the report as needed.",
- "operationId": "getPromotionReports",
- "parameters": [
- {
- "name": "limit",
- "in": "query",
- "description": "Specifies the maximum number of promotions returned on a page from the result set.
Default: 200
Maximum: 200",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "marketplace_id",
- "in": "query",
- "description": "The eBay marketplace ID of the site for which you want the promotions report. Valid values:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "Specifies the number of promotions to skip in the result set before returning the first promotion in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "promotion_status",
- "in": "query",
- "description": "Limits the results to the promotions that are in the state specified by this query parameter.
Valid values: DRAFTSCHEDULEDRUNNINGPAUSEDENDED
Maximum number of values supported: 1",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "promotion_type",
- "in": "query",
- "description": "Filters the returned promotions in the report based on their campaign promotion type. Specify one of the following values to indicate the promotion type you want returned in the report: CODED_COUPON – A coupon code promotion set with createItemPromotion.MARKDOWN_SALE – A markdown promotion set with createItemPriceMarkdownPromotion.ORDER_DISCOUNT – A threshold promotion set with createItemPromotion.VOLUME_DISCOUNT – A volume pricing promotion set with createItemPromotion.
",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "q",
- "in": "query",
- "description": "A string consisting of one or more keywords. eBay filters the response by returning only the promotions that contain the supplied keywords in the promotion title.
Example: \"iPhone\" or \"Harry Potter.\"
Commas that separate keywords are ignored. For example, a keyword string of \"iPhone, iPad\" equals \"iPhone iPad\", and each results in a response that contains promotions with both \"iPhone\" and \"iPad\" in the title.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/PromotionsReportPagedCollection"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- },
- "38211": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The offset value must be an integer value greater than or equal to zero."
- },
- "38213": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "You can query a limit of between 0 and 200 promotion records at a time. Update the request and resubmit the call."
- },
- "38240": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
- },
- "345141": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "Invalid input for the 'promotionType' field. For help, see the documentation for this call."
- }
- }
- }
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/promotion_summary_report": {
- "get": {
- "tags": [
- "promotion_summary_report"
- ],
- "description": "This method generates a report that summarizes the seller's promotions for the specified eBay marketplace. The report returns information on RUNNING, PAUSED, and ENDED promotions (deleted reports are not returned) and summarizes the seller's campaign performance for all promotions on a given site.
For information about summary reports, see Reading the item promotion Summary report.",
- "operationId": "getPromotionSummaryReport",
- "parameters": [
- {
- "name": "marketplace_id",
- "in": "query",
- "description": "The eBay marketplace ID of the site you for which you want a promotion summary report. Valid values:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/SummaryReportResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "38204": {
- "domain": "API_MARKETING",
- "category": "REQUEST",
- "description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "38201": {
- "domain": "API_MARKETING",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/email_campaign": {
- "get": {
- "tags": [
- "email_campaign"
- ],
- "description": "This method retrieves a list of email campaigns from a seller's eBay store.
Users can filter the results by email campaign type, email campaign status, and marketplace ID using the q query parameter.",
- "operationId": "getEmailCampaigns",
- "parameters": [
- {
- "name": "limit",
- "in": "query",
- "description": "The maximum number of email campaigns returned in a page.
Min value: 1
Max value: 200",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "The number of results to skip in a pagination query. This value cannot be less than zero.
Default value: 0",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "q",
- "in": "query",
- "description": "This field contains filter criteria for the results returned. Filter by email campaign type, email campaign status, and marketplace ID.
For example, setting q=campaignType:WELCOME,ITEM_SHOWCASE;status:ACTIVE will return only active Welcome and Item Showcase email campaigns.
If no filter is set up through the q query parameter, all of the seller's campaigns will be returned in the results set. ",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "sort",
- "in": "query",
- "description": "The criteria for sorting email campaign results. See ItemSortEnum for sorting options and their enum values.
Default: NEWLY_LISTED",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/GetEmailCampaignsResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "STORE_CRM",
- "category": "BUSINESS",
- "description": "A store subscription is required for this call, please check the store subscription status for current seller."
- },
- "35301": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The paginated query limit {limit} value is missing or invalid. The value cannot be less than or equal to zero and also cannot be greater than maximum value."
- },
- "35302": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The paginated query offset {offset} value is missing or invalid. The value cannot be less zero and also cannot be greater than maximum value."
- },
- "35303": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The query string {q} is malformed. For the valid format, see the documentation for this call."
- },
- "35304": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The email campaign type {campaignType} in query string {q} is not supported. For the valid values, see the documentation for this call."
- },
- "35305": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The 'marketplaceId' in query string {q} is not supported. For the valid values, see the documentation for this call."
- },
- "35306": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The email campaign status {status} in query string {q} is not supported. For the valid values, see the documentation for this call."
- },
- "35307": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The campaign type {campaignType} in query string {q} is required."
- }
- }
- }
- },
- "409": {
- "description": "Conflict"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35000": {
- "domain": "STORE_CRM",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "post": {
- "tags": [
- "email_campaign"
- ],
- "description": "This method creates a new email campaign. An eBay store owner can create six different types of email campaigns: Welcome, New products & collections, Coupon, Sale event + markdown, Order discount, and Volume pricing.
A successful createEmailCampaign request returns the emailCampaignId assigned to the new email campaign.
The fields emailCampaignType, audienceCodes, itemSelectMode, subject, and personalizedMessage are required for all email campaign types.
Specific email campaign types have required values for additional fields. For more information on the email campaign types, see the Store Email Campaigns section of the Selling Integration Guide. ",
- "operationId": "createEmailCampaign",
- "parameters": [
- {
- "name": "X-EBAY-C-MARKETPLACE-ID",
- "in": "header",
- "description": "The eBay marketplace that the email campaign interfaces with.
eBay marketplaces correspond to geographical regions or large submarkets of regions. For example, EBAY-US corresponds to the United States market.
See the full list of marketplace IDs.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "Create a new email campaign request.",
- "content": {
- "application/json": {
- "schema": {
- "description": "Create a new email campaign request.",
- "$ref": "#/components/schemas/CreateEmailCampaignRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "OK",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/CreateEmailCampaignResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "STORE_CRM",
- "category": "BUSINESS",
- "description": "A store subscription is required for this call, please check the store subscription status for current seller."
- },
- "35201": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'marketplaceId' value is not supported. For the valid values, see the documentation for this call."
- },
- "35202": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'emailCampaignType' value is not supported. For the valid values, see the documentation for this call."
- },
- "35203": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'audiences' is required for this call."
- },
- "35204": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'subject' is required for this call."
- },
- "35205": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'personalizedMessage' is required for this call."
- },
- "35206": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'subject' length is too long. For maximum limits, see the documentation for this call."
- },
- "35207": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'audiences' value is not suitable for current email campaign type."
- },
- "35208": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'itemIds' is required for this call."
- },
- "35209": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "For 'WELCOME' type campaign, 'itemIds' should be empty."
- },
- "35210": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The item {itemIds} size exceeds maximum. For maximum limits, see the documentation for this call."
- },
- "35211": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "No eligible items for current campaign."
- },
- "35212": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'promotionId' is required for this call."
- },
- "35213": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'promotionId' is invalid, promotion may be inactive or non-exist."
- },
- "35214": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'scheduleDate' is not required for this call."
- },
- "35215": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'scheduleDate' is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm.sssZ) string."
- },
- "35216": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "Only one 'WELCOME' type email campaign is allowed for one marketplace."
- },
- "35217": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "Only one automated promotion email campaign is allowed for one campaign type per marketplace id."
- },
- "35218": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'personalizedMessage' length is too long. For maximum limits, see the documentation for this call."
- },
- "35219": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The email campaign schedule date {scheduleDate} must be in the future."
- },
- "35220": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'itemIds' contains ineligible item id, please check the item list"
- },
- "35221": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'itemSelectMode' is invalid for this campaign, please see the documentation for this call."
- }
- }
- }
- },
- "409": {
- "description": "Conflict"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35000": {
- "domain": "STORE_CRM",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/email_campaign/{email_campaign_id}": {
- "get": {
- "tags": [
- "email_campaign"
- ],
- "description": "This method returns the details of a single email campaign specified by the email_campaign_id path parameter.
Call getEmailCampaigns to retrieve a list of all email campaigns from a seller's eBay store.",
- "operationId": "getEmailCampaign",
- "parameters": [
- {
- "name": "email_campaign_id",
- "in": "path",
- "description": "The unique eBay-assigned ID of the email campaign.
Call getEmailCampaigns to retrieve a list of email campaign IDs for a seller. Use the emailCampaignId value of the desired email campaign.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/GetEmailCampaignResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "STORE_CRM",
- "category": "BUSINESS",
- "description": "A store subscription is required for this call, please check the store subscription status for current seller."
- },
- "35501": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "No email campaign found for email campaign ID {email_campaign_id}."
- }
- }
- }
- },
- "409": {
- "description": "Conflict"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35000": {
- "domain": "STORE_CRM",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "put": {
- "tags": [
- "email_campaign"
- ],
- "description": "This method lets users update an existing email campaign. Pass the emailCampaignId in the request URL and specify the changes to field values in the request payload.
Note: You can only update the custom fields of an email campaign. Fixed values, such as the emailCampaignType, cannot be changed. For full specifications of fixed values for each email campaign type, see the createEmailCampaign method documentation.",
- "operationId": "updateEmailCampaign",
- "parameters": [
- {
- "name": "email_campaign_id",
- "in": "path",
- "description": "The email campaign id assigned by the system when the email campaign is created. Call getEmailCampaigns to retrieve a list of email campaign IDs for a seller.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Content-Type",
- "in": "header",
- "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "description": "update email campaign request",
- "content": {
- "application/json": {
- "schema": {
- "description": "update email campaign request",
- "$ref": "#/components/schemas/UpdateCampaignRequest"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "OK",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/UpdateEmailCampaignResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "STORE_CRM",
- "category": "BUSINESS",
- "description": "A store subscription is required for this call, please check the store subscription status for current seller."
- },
- "35801": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'audiences' is required for this call."
- },
- "35802": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "No email campaign found for email campaign ID {email_campaign_id}."
- },
- "35803": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'subject' is required for this call."
- },
- "35804": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'personalizedMessage' is required for this call."
- },
- "35805": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'subject' length is too long. For maximum limits, see the documentation for this call."
- },
- "35806": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'audiences' value is not suitable for current email campaign type."
- },
- "35807": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'itemIds' is required for this call."
- },
- "35808": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "For 'WELCOME' type campaign, 'itemIds' should be empty."
- },
- "35809": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The item {itemIds} size exceeds maximum. For maximum limits, see the documentation for this call."
- },
- "35810": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "No eligible items for current campaign."
- },
- "35811": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'promotionId' is required for this call."
- },
- "35812": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'promotionId' is invalid, promotion may be inactive or non-exist."
- },
- "35813": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'scheduleDate' is not required for this call."
- },
- "35814": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'scheduleDate' is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm:sssZ) string."
- },
- "35815": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'email_campaign_id' is not eligible for editing."
- },
- "35816": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'personalizedMessage' length is too long. For maximum limits, see the documentation for this call."
- },
- "35817": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The email campaign schedule date {scheduleDate} must be in the future."
- },
- "35818": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'itemIds' contains ineligible item id, please check the item list"
- },
- "35819": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'itemSelectMode' is invalid for this campaign, please see the documentation for this call."
- }
- }
- }
- },
- "409": {
- "description": "Conflict"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35000": {
- "domain": "STORE_CRM",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- },
- "delete": {
- "tags": [
- "email_campaign"
- ],
- "description": "This method deletes the email campaign specified by the email_campaign_id path parameter.
Call getEmailCampaigns to retrieve all of the seller's email campaigns. Use the email_campaign_id of the desired email campaign in the response as the path parameter for this request.",
- "operationId": "deleteEmailCampaign",
- "parameters": [
- {
- "name": "email_campaign_id",
- "in": "path",
- "description": "A unique eBay-assigned ID for an email campaign that is generated when an email campaign is created.
Note: You can retrieve the email campaign IDs for a specified seller using the getEmailCampaigns method.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/DeleteEmailCampaignResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "STORE_CRM",
- "category": "BUSINESS",
- "description": "A store subscription is required for this call, please check the store subscription status for current seller."
- },
- "35401": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "No email campaign found for email campaign ID {email_campaign_id}."
- }
- }
- }
- },
- "409": {
- "description": "Conflict"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35000": {
- "domain": "STORE_CRM",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/email_campaign/audience": {
- "get": {
- "tags": [
- "email_campaign"
- ],
- "description": "This method retrieves all available email newsletter audiences for the email campaign type specified by the emailCampaignType path parameter.
Use the optional limit and offset path parameters to paginate the results and to control which records are returned, respectively.",
- "operationId": "getAudiences",
- "parameters": [
- {
- "name": "emailCampaignType",
- "in": "query",
- "description": "The email campaign type to search against. See CampaignTypeEnum for the full list of available email campaign types and associated enum values.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "limit",
- "in": "query",
- "description": "The maximum number of audience groups returned per page in the results set.
Min value: 1
Max value: 200
Default value: 100",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "offset",
- "in": "query",
- "description": "The number of results to skip in a pagination query. This value cannot be less than 0.
Default value: 0",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/GetEmailCampaignAudiencesResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "STORE_CRM",
- "category": "BUSINESS",
- "description": "A store subscription is required for this call, please check the store subscription status for current seller."
- },
- "35101": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The paginated query limit {limit} value is missing or invalid. The value cannot be less than or equal to zero."
- },
- "35102": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The paginated query offset {offset} value is mossing or invalid. The value cannot be less than zero."
- },
- "35103": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The email campaign type {emailCampaignType} is not supported. For the valid value, please see the documentation for this call."
- }
- }
- }
- },
- "409": {
- "description": "Conflict"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35000": {
- "domain": "STORE_CRM",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/email_campaign/{email_campaign_id}/email_preview": {
- "get": {
- "tags": [
- "email_campaign"
- ],
- "description": "This method returns a preview of the email sent by the email campaign indicated by the email_campaign_id path parameter.
Call getEmailCampaigns to obtain a list of email campaigns. Use the emailCampaignId value of the desired email campaign as the email_campaign_id path parameter value.
If this call is executed successfully, the response returns a content field that contains the raw HTML code of the email campaign that can then be rendered anywhere.
Note: The eBay listings in the email are sorted according to the email campaign sort criteria. The individual listings can change over time, as well.
The result of the email preview call can be treated as a snapshot of the email campaign taken at the date and time of the renderDate value found in the results of the call.",
- "operationId": "getEmailPreview",
- "parameters": [
- {
- "name": "email_campaign_id",
- "in": "path",
- "description": "The email campaign id assigned by the system when the email campaign is created. Call getEmailCampaigns to retrieve a list of email campaign IDs for a seller.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/GetEmailPreviewResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "STORE_CRM",
- "category": "BUSINESS",
- "description": "A store subscription is required for this call, please check the store subscription status for current seller."
- },
- "35601": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "No email campaign found for email campaign ID {email_campaign_id}."
- }
- }
- }
- },
- "409": {
- "description": "Conflict"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35000": {
- "domain": "STORE_CRM",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- },
- "/email_campaign/report": {
- "get": {
- "tags": [
- "email_campaign"
- ],
- "description": "This method returns the seller's email campaign performance report for a time period specified by the startDate and endDate path parameters. The maximum date range for a report retrieved by this method is one year.
Note: The startDate and endDate must be given in UTC format, as shown in the following example:
sell/marketing/v1/email_campaign/report?startDate=2022-11-01T19:09:02.768Z&endDate=2022-12-28T19:09:02.768Z
The email report returns a list of metrics, such as the number of times an email report has been opened and resulted in clicks.",
- "operationId": "getEmailReport",
- "parameters": [
- {
- "name": "endDate",
- "in": "query",
- "description": "The end date for the report, given in UTC format. The maximum date range for a report retrieved by this method is one year.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "startDate",
- "in": "query",
- "description": "The start date for the report, given in UTC format. The maximum date range for a report retrieved by this method is one year.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/GetEmailReportResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "35001": {
- "domain": "STORE_CRM",
- "category": "BUSINESS",
- "description": "A store subscription is required for this call, please check the store subscription status for current seller."
- },
- "35701": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'startDate' value is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm:sssZ) string."
- },
- "35702": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'endDate' value is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm:sssZ) string."
- },
- "35703": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The query start date {startDate} cannot be later than query end date {endDate}."
- },
- "35704": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "The time interval between start date and end date exceeds maximum limit. For maximum limits, please see the documentation for this call."
- },
- "35705": {
- "domain": "STORE_CRM",
- "category": "REQUEST",
- "description": "'currency' value is not supported. For the valid values, see the documentation for this call."
- }
- }
- }
- },
- "409": {
- "description": "Conflict"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "35000": {
- "domain": "STORE_CRM",
- "category": "APPLICATION",
- "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
- }
- }
- }
- }
- },
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope/sell.marketing"
- ]
- }
- ]
- }
- }
- },
- "components": {
- "schemas": {
- "Ad": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model. This ID is created after a successful createAdGroup call, and all ad groups must be associated with a CPC campaign."
- },
- "adId": {
- "type": "string",
- "description": "A unique eBay-assigned ID that is generated when the ad is created."
- },
- "adStatus": {
- "type": "string",
- "description": "The current status of the CPC ad.
Valid Values:Note: This type only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model. For implementation help, refer to eBay API documentation"
- },
- "alerts": {
- "type": "array",
- "description": "An array containing alert messages for the ad.",
- "items": {
- "$ref": "#/components/schemas/Alert"
- }
- },
- "bidPercentage": {
- "type": "string",
- "description": "The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
This is default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.
Note:This field will always be returned for campaigns that use the Cost Per Sale (CPS) funding model. It will not be returned for campaigns that use the Cost Per Click (CPC) funding model.
Minimum value: 2.0
Maximum value: 100.0"
- },
- "inventoryReferenceId": {
- "type": "string",
- "description": "An ID that identifies a single-item listing or multiple-variation listing that is managed with the Inventory API. The inventory reference ID is a seller-defined value that can be either an SKU for a single-item listing or an inventoryItemGroupKey for a multiple-value listing.
An inventoryItemGroupKey is a value that the seller defines to indicate a listing that's the parent of an inventory item group (a multiple-variation listing, such as a listing for a shirt that's available in multiple sizes and colors).
This field is only returned if the ad is associated with a SKU or an inventory item group value.
"
- },
- "inventoryReferenceType": {
- "type": "string",
- "description": "The enumeration value returned here indicates the type of listing the inventoryReferenceId references. The value returned here will be INVENTORY_ITEM for a single-variation listing, or INVENTORY_ITEM_GROUP for a multiple-variation listing. This field is only returned if the ad is associated with a SKU or an inventory item group value.
For implementation help, refer to eBay API documentation"
- },
- "listingId": {
- "type": "string",
- "description": "A unique eBay-assigned ID that is generated when a listing is created."
- }
- },
- "description": "A type that defines the fields for an ad."
- },
- "AdGroup": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model."
- },
- "adGroupStatus": {
- "type": "string",
- "description": "An enumeration value representing the current status of the ad group.
Valid Values: For implementation help, refer to eBay API documentation"
- },
- "defaultBid": {
- "description": "A bid amount that applies to all of the keywords in an ad group that do not have individual bids. For all keywords without individual bids, the default bid is the amount that the seller will pay per click for the listings in the ad group in the promoted listings campaign.
Valid Values: 0.5, 0.75",
- "$ref": "#/components/schemas/Amount"
- },
- "name": {
- "type": "string",
- "description": "The seller-defined name of the ad group."
- }
- },
- "description": "A container for the details of an existing ad group.
An ad group can be added to a campaign that uses the Cost Per Click (CPC) funding model. A campaign may have multiple ad groups. All listings that are promoted in the campaign are included in the ad group.
Note: This type only applies to the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model."
- },
- "AdGroupPagedCollectionResponse": {
- "type": "object",
- "properties": {
- "adGroups": {
- "type": "array",
- "description": "The details of existing ad groups, such as the name, ID, and status of the ad groups.",
- "items": {
- "$ref": "#/components/schemas/AdGroup"
- }
- },
- "href": {
- "type": "string",
- "description": "The URI of the current page of results from the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set."
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Default: 0
Note: The items in a paginated result set use a zero-based list, where the first item in the list has an offset of 0.",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results."
- },
- "total": {
- "type": "integer",
- "description": "The total number of items retrieved in the result set.
Note: If no items are found, this field is returned with a value of 0.",
- "format": "int32"
- }
- },
- "description": "A container for the details of a paged collection of ad groups.
Note: This type only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model."
- },
- "AdIds": {
- "type": "object",
- "properties": {
- "adIds": {
- "type": "array",
- "description": "A list of ad IDs. Only one ad can be deleted per operation and only one adId value will be returned.",
- "items": {
- "type": "string"
- }
- }
- },
- "description": "This type is a container for a list of ad IDs."
- },
- "AdPagedCollectionResponse": {
- "type": "object",
- "properties": {
- "ads": {
- "type": "array",
- "description": "The list of ads that matched the request criteria.",
- "items": {
- "$ref": "#/components/schemas/Ad"
- }
- },
- "href": {
- "type": "string",
- "description": "The URI of the current page of results from the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.Default: 10",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the next page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be increased to retrieve the next page of results.
Max length: 2048"
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first result on the current page. This value can be set in the request with the offset query parameter. If the offset value is not set, it defaults to zero.
Default: 0
Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results.
Max length: 2048"
- },
- "total": {
- "type": "integer",
- "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
- "format": "int32"
- }
- },
- "description": "This type defines the fields that paginate the ads returned by the request. The entire result set consists of 0 or more sequenced response pages, where each page consists of 0 or more items from the complete result set."
- },
- "AdReference": {
- "type": "object",
- "properties": {
- "adId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for an ad. This ID is generated when an ad is created."
- },
- "href": {
- "type": "string",
- "description": "The getAd URI of an ad. You can use this URI to retrieve the ad."
- }
- },
- "description": "This type defines the fields for an ad ID and its associated URL."
- },
- "AdReferences": {
- "type": "object",
- "properties": {
- "ads": {
- "type": "array",
- "description": "A list of ad IDs. An ad ID is generated for each successfully created ad. Only one ad can be created per operation.",
- "items": {
- "$ref": "#/components/schemas/AdReference"
- }
- }
- },
- "description": "This type is a container for a list of ad IDs and their associated URIs."
- },
- "AdResponse": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for an ad group in a Promoted Listings Advanced (PLA) campaign that uses the Cost Per Click (CPC) funding model.Note: This field will always be returned for campaigns that use the CPC funding model. It will not be returned for campaigns that use the Cost Per Sale (CPS) funding model."
- },
- "adId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for an ad. This ID is generated when an ad is created.Note:This field is only returned when an ad is successfully created for the corresponding listing."
- },
- "errors": {
- "type": "array",
- "description": "An array of errors associated with the request.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "href": {
- "type": "string",
- "description": "The getAd URI that points to the ad.Note:This field is only returned when an ad is successfully created for the corresponding listing."
- },
- "listingId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a listing that is generated when the listing is created."
- },
- "statusCode": {
- "type": "integer",
- "description": "An HTTP status code indicating if the corresponding ad was successfully created or not. 200 Successful should be returned for successfully created ads.Note:A status code is returned for each ad that the seller creates, or attempts to create.",
- "format": "int32"
- }
- },
- "description": "This type defines the fields returned in an ad response."
- },
- "AdUpdateResponse": {
- "type": "object",
- "properties": {
- "adId": {
- "type": "string",
- "description": "A unique eBay-assigned ID that is generated when the ad is created."
- },
- "errors": {
- "type": "array",
- "description": "A list of errors associated with the specified listing ID.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "href": {
- "type": "string",
- "description": "The URI for the ad, which can be used to retrieve the ad."
- },
- "listingId": {
- "type": "string",
- "description": "A unique eBay-assigned ID that is generated when the listing is created."
- },
- "statusCode": {
- "type": "integer",
- "description": "An HTTP status code that indicates the response-status of the request.",
- "format": "int32"
- }
- },
- "description": "A type that contains the fields for the ad update response."
- },
- "AdUpdateStatusByListingIdResponse": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model."
- },
- "errors": {
- "type": "array",
- "description": "A list of errors associated with the specified listing ID.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "href": {
- "type": "string",
- "description": "The URI for the ad, which can be used to retrieve the ad."
- },
- "listingId": {
- "type": "string",
- "description": "A unique eBay-assigned ID that is generated when the listing is created."
- },
- "statusCode": {
- "type": "integer",
- "description": "An HTTP status code that indicates the response-status of the request.",
- "format": "int32"
- }
- },
- "description": "A type that contains the fields for the ad update status by listing ID response."
- },
- "AdUpdateStatusResponse": {
- "type": "object",
- "properties": {
- "adId": {
- "type": "string",
- "description": "A unique eBay-assigned ID that is generated when the ad is created."
- },
- "errors": {
- "type": "array",
- "description": "A list of errors associated with the specified listing ID.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "href": {
- "type": "string",
- "description": "The URI for the ad, which can be used to retrieve the ad."
- },
- "statusCode": {
- "type": "integer",
- "description": "An HTTP status code that indicates the response-status of the request.",
- "format": "int32"
- }
- },
- "description": "A type that contains the fields for the ad update status response."
- },
- "AdditionalInfo": {
- "type": "object",
- "properties": {
- "infoType": {
- "type": "string",
- "description": "The type of additional information provided for the suggested keyword.
Valid Value: KEYWORD_INSIGHTS For implementation help, refer to eBay API documentation"
- },
- "metrics": {
- "type": "array",
- "description": "A list of additional data provided for the suggested keyword.",
- "items": {
- "$ref": "#/components/schemas/AdditionalInfoData"
- }
- }
- },
- "description": "A type that provides additional information for suggested keywords."
- },
- "AdditionalInfoData": {
- "type": "object",
- "properties": {
- "metricKey": {
- "type": "string",
- "description": "The metric used to provide additional information for the suggested keyword.
Valid Values: ACTIVE_SELLER_COUNTSEARCH_VOLUME
For implementation help, refer to eBay API documentation"
- },
- "value": {
- "type": "string",
- "description": "The data provided for the specified metric.
Note: All metric data is compiled for the marketplace associated with the specified campaign ID."
- }
- },
- "description": "A type that defines the data produced for additional information about suggested keywords."
- },
- "Ads": {
- "type": "object",
- "properties": {
- "ads": {
- "type": "array",
- "description": "A list of ad IDs. An ad ID is generated for each successfully created ad.",
- "items": {
- "$ref": "#/components/schemas/Ad"
- }
- }
- },
- "description": "This type defines the container for an array of ads."
- },
- "Alert": {
- "type": "object",
- "properties": {
- "alertType": {
- "type": "string",
- "description": "The type of alert message. For example, an invalid bid percentage. For implementation help, refer to eBay API documentation"
- },
- "details": {
- "type": "array",
- "description": "A description of the alert including dimensions and aspects.",
- "items": {
- "$ref": "#/components/schemas/AlertDetails"
- }
- }
- },
- "description": "A type that contains the alert message fields for the ad."
- },
- "AlertDetails": {
- "type": "object",
- "properties": {
- "dimension": {
- "description": "The dimension information of the alert including keys and values.",
- "$ref": "#/components/schemas/AlertDimension"
- },
- "aspect": {
- "description": "The aspect information of the alert including keys and values.",
- "$ref": "#/components/schemas/Aspect"
- }
- },
- "description": "A type that contains the alert detail fields."
- },
- "AlertDimension": {
- "type": "object",
- "properties": {
- "key": {
- "type": "string",
- "description": "The key field of the applied dimension. For example, the marketplace Id. For implementation help, refer to eBay API documentation"
- },
- "value": {
- "type": "string",
- "description": "The value field of the applied dimension. For example, if the key is a MARKETPLACE_ID, the value would be from MarketplaceIdEnum."
- }
- },
- "description": "A type that contains the dimension fields."
- },
- "Amount": {
- "type": "object",
- "properties": {
- "currency": {
- "type": "string",
- "description": "The base currency applied to the value field to establish a monetary amount.
The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.
Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation"
- },
- "value": {
- "type": "string",
- "description": "The monetary amount in the specified currency.
Required in the amount type."
- }
- },
- "description": "A complex type that describes the value of a monetary amount as represented by a global currency."
- },
- "Aspect": {
- "type": "object",
- "properties": {
- "key": {
- "type": "string",
- "description": "The type of the aspect. For example, MINIMUM_REQUIRED. For implementation help, refer to eBay API documentation"
- },
- "value": {
- "type": "string",
- "description": "The value of the aspect. For example, if the aspect is a percentage, a value of '2.0' would equal 2%."
- }
- },
- "description": "A type that contains the aspect fields."
- },
- "BaseResponse": {
- "type": "object",
- "properties": {
- "warnings": {
- "type": "array",
- "description": "The container for any warning error messages generated by the request. Warnings are not fatal in that they do not prevent the call from running and returning a response, but they should be reviewed to ensure your requests are returning the responses you expect.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type defines the fields for any warning error messages."
- },
- "Budget": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "The allocated budget amount for a CPC Promoted Listings campaign.",
- "$ref": "#/components/schemas/Amount"
- },
- "budgetStatus": {
- "type": "string",
- "description": "The budget status for a CPC Promoted Listings campaign. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A container for the budget details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model.
Note: This container will only be returned for campaigns using the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model."
- },
- "BudgetRequest": {
- "type": "object",
- "properties": {
- "amount": {
- "description": "The allocated budget amount for a CPC Promoted Listings campaign. Both the currency and value must be specified.",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "A container for the budget details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model.
Note: This container will only be returned for campaigns using the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model."
- },
- "BulkAdResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "This array displays the list of ads that were successfully created. For any ads that were not created successfully, the errors array may provide more detail about why creation of one or more ads failed.",
- "items": {
- "$ref": "#/components/schemas/AdResponse"
- }
- }
- },
- "description": "This type defines the fields for the create ads in bulk response."
- },
- "BulkAdUpdateResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "A set of ad listings processed by the call.",
- "items": {
- "$ref": "#/components/schemas/AdUpdateResponse"
- }
- }
- },
- "description": "A type that defines the fields for updated ads in the bulk response."
- },
- "BulkAdUpdateStatusByListingIdResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "An array of processed ad listings in bulk.",
- "items": {
- "$ref": "#/components/schemas/AdUpdateStatusByListingIdResponse"
- }
- }
- },
- "description": "A type that defines the fields for the updated ad status in the bulk response."
- },
- "BulkAdUpdateStatusResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "An array of processed ad listings in bulk.",
- "items": {
- "$ref": "#/components/schemas/AdUpdateStatusResponse"
- }
- }
- },
- "description": "A type that defines the fields for the updated ad status in the bulk response."
- },
- "BulkCreateAdRequest": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "An array of listing IDs and their associated bid percentages, which the request uses to create ads in bulk. This request accepts both listing IDs, as generated by the Inventory API, and an item IDs, as used in the eBay Traditional API set (e.g., the Trading and Finding APIs).
Maximum: 500 IDs per call",
- "items": {
- "$ref": "#/components/schemas/CreateAdRequest"
- }
- }
- },
- "description": "This type defines the fields for the create ads in bulk by listing IDs."
- },
- "BulkCreateAdsByInventoryReferenceRequest": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "A list of inventory reference ID and inventory reference type pairs, and the bid percentage, which the call uses to create ads in bulk.",
- "items": {
- "$ref": "#/components/schemas/CreateAdsByInventoryReferenceRequest"
- }
- }
- },
- "description": "This type defines the fields used to create ads in bulk by inventory reference IDs."
- },
- "BulkCreateAdsByInventoryReferenceResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "This array displays the list of ads that were successfully created. For any ads that were not created successfully, the errors array may provide more detail about why creation of one or more ads failed.",
- "items": {
- "$ref": "#/components/schemas/CreateAdsByInventoryReferenceResponse"
- }
- }
- },
- "description": "This type defines the response fields used by the bulkCreateAdsByInventoryReference method."
- },
- "BulkCreateKeywordRequest": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "This array is used to pass in multiple keywords for one or more ad groups that belong to a campaign that uses the Cost Per Click (CPC) funding model. Up to {max value} keywords can be created with one call.",
- "items": {
- "$ref": "#/components/schemas/CreateKeywordRequest"
- }
- }
- },
- "description": "A type that contains the fields for the bulk request to create keywords."
- },
- "BulkCreateKeywordResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "A list of keywords that have been processed by the request.",
- "items": {
- "$ref": "#/components/schemas/KeywordResponse"
- }
- }
- },
- "description": "A type that contains the response fields for the bulk request to create keywords."
- },
- "BulkCreateNegativeKeywordRequest": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "This array is used to pass in multiple negative keywords for one or more ad groups that belong to a campaign that uses the Cost Per Click (CPC) funding model.",
- "items": {
- "$ref": "#/components/schemas/CreateNegativeKeywordRequest"
- }
- }
- },
- "description": "A type that contains the fields for the bulk request to create negative keywords."
- },
- "BulkCreateNegativeKeywordResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "A list of negative keywords that have been processed by the request.",
- "items": {
- "$ref": "#/components/schemas/NegativeKeywordResponse"
- }
- }
- },
- "description": "A type that contains the response fields for the bulk request to create negative keywords."
- },
- "BulkDeleteAdRequest": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "An array of the listing IDs that identify the ads to remove.",
- "items": {
- "$ref": "#/components/schemas/DeleteAdRequest"
- }
- }
- },
- "description": "This type defines the fields that the call uses to remove ads in bulk."
- },
- "BulkDeleteAdResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "An array of the ads that were deleted by the bulkDeleteAdsByListingId request, including information associated with each individual delete request.",
- "items": {
- "$ref": "#/components/schemas/DeleteAdResponse"
- }
- }
- },
- "description": "This type defines a container that lists the ads that bulkDeleteAdsByListingId deleted."
- },
- "BulkDeleteAdsByInventoryReferenceRequest": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "A list of inventory referenceID and inventory reference type pairs that specify the set of ads to remove in bulk.",
- "items": {
- "$ref": "#/components/schemas/DeleteAdsByInventoryReferenceRequest"
- }
- }
- },
- "description": "This type defines the request fields that bulkDeleteAdsByInventoryReference uses to delete ads in bulk."
- },
- "BulkDeleteAdsByInventoryReferenceResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "An array of the ads that were deleted by the bulkDeleteAdsByInventoryReference request, including information associated with each individual delete request.",
- "items": {
- "$ref": "#/components/schemas/DeleteAdsByInventoryReferenceResponse"
- }
- }
- },
- "description": "This type defines a container that lists the ads that bulkDeleteAdsByInventoryReference deleted."
- },
- "BulkUpdateAdStatusByListingIdRequest": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "An array of listing IDs and bid percentages.",
- "items": {
- "$ref": "#/components/schemas/UpdateAdStatusByListingIdRequest"
- }
- }
- },
- "description": "A type that defines the fields for the BulkUpdateAdStatusByListingId request."
- },
- "BulkUpdateAdStatusRequest": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "An array of listing IDs and bid percentages.",
- "items": {
- "$ref": "#/components/schemas/UpdateAdStatusRequest"
- }
- }
- },
- "description": "A type that defines the fields for the BulkUpdateAdStatus request."
- },
- "BulkUpdateAdsByInventoryReferenceResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "A list of inventory references that were processed from the request.",
- "items": {
- "$ref": "#/components/schemas/UpdateAdsByInventoryReferenceResponse"
- }
- }
- },
- "description": "A type that defines the fields for the BulkUpdateAdStatusByInventoryReference response."
- },
- "BulkUpdateKeywordRequest": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "Use this array to update the bid values and/or statuses of one or more existing keywords.",
- "items": {
- "$ref": "#/components/schemas/UpdateKeywordByKeywordIdRequest"
- }
- }
- },
- "description": "A type that defines the fields for the BulkUpdateKeyword request."
- },
- "BulkUpdateKeywordResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "A list of keywords that have been processed from the bulk request.",
- "items": {
- "$ref": "#/components/schemas/UpdateKeywordResponse"
- }
- }
- },
- "description": "A type that defines the fields for the BulkUpdateKeyword response."
- },
- "BulkUpdateNegativeKeywordRequest": {
- "type": "object",
- "properties": {
- "requests": {
- "type": "array",
- "description": "An array to update the statuses of one or more existing negative keywords.",
- "items": {
- "$ref": "#/components/schemas/UpdateNegativeKeywordIdRequest"
- }
- }
- },
- "description": "A type that defines the fields for the BulkUpdateNegativeKeyword request."
- },
- "BulkUpdateNegativeKeywordResponse": {
- "type": "object",
- "properties": {
- "responses": {
- "type": "array",
- "description": "A list of negative keywords that have been processed from the bulk request.",
- "items": {
- "$ref": "#/components/schemas/UpdateNegativeKeywordResponse"
- }
- }
- },
- "description": "A type that defines the fields for the BulkUpdateNegativeKeyword response."
- },
- "Campaign": {
- "type": "object",
- "properties": {
- "alerts": {
- "type": "array",
- "description": "This array contains alert messages for the campaign.",
- "items": {
- "$ref": "#/components/schemas/Alert"
- }
- },
- "budget": {
- "description": "The allocated budget for the Cost Per Click (CPC) Promoted Listings campaign.Note: This field will only be returned for campaigns using the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model.",
- "$ref": "#/components/schemas/CampaignBudget"
- },
- "campaignCriterion": {
- "description": "The selection rules (criterion) used to select the listings for a campaign. If you populate the campaignCriterion object in your createCampaign request, ads for the campaign are created by rule for the listings that meet the criteria you specify, and these ads are associated with the campaign.Note: This container is only returned for rules-based campaigns using the Cost Per Sale (CPS) funding model.",
- "$ref": "#/components/schemas/CampaignCriterion"
- },
- "campaignId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created."
- },
- "campaignName": {
- "type": "string",
- "description": "A seller-defined name for the campaign. This value must be unique for the seller. You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters"
- },
- "campaignStatus": {
- "type": "string",
- "description": "Indicates the status of the campaign, such as RUNNING, PAUSED, and ENDED. For implementation help, refer to eBay API documentation"
- },
- "endDate": {
- "type": "string",
- "description": "The date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is omitted, the campaign will have no defined end date, and will not end until the seller makes a decision to end the campaign with an endCampaign call, or if they update the campaign at a later time with an end date."
- },
- "fundingStrategy": {
- "description": "This container shows the funding model used for the campaign, and the default bid percentage for a campaign that uses the Cost Per Sale (CPS) funding model. Currently, the supported funding models are COST_PER_SALE and COST_PER_CLICK.",
- "$ref": "#/components/schemas/FundingStrategy"
- },
- "marketplaceId": {
- "type": "string",
- "description": "The ID of the eBay marketplace where the campaign is hosted. For implementation help, refer to eBay API documentation"
- },
- "startDate": {
- "type": "string",
- "description": "The date and time the campaign starts, in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller.
On the date specified, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts after this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign. Call getCampaign to check the status of the campaign.
"
- }
- },
- "description": "This type defines the fields that describe an ad campaign."
- },
- "CampaignAudience": {
- "type": "object",
- "properties": {
- "audienceType": {
- "type": "string",
- "description": "This enum value indicates the audience type. For the complete list of audience types and their associated enum values, see AudienceTypeEnum. For implementation help, refer to eBay API documentation"
- },
- "code": {
- "type": "string",
- "description": "The unique code for an audience. "
- },
- "name": {
- "type": "string",
- "description": "The display name for an audience."
- }
- },
- "description": "This is the object for a single email campaign audience."
- },
- "CampaignBudget": {
- "type": "object",
- "properties": {
- "daily": {
- "description": "The daily budget limit for the Cost Per Click (CPC) Promoted Listings campaign.
Required if the campaign's funding model is CPC.
This will be a dollar value. All clicks using the keywords defined for the campaign will go towards expending the daily budget. Once the daily budget is exceeded for the campaign, all Promoted Listings under the campaign will be turned off until the next day.
Valid Values:",
- "$ref": "#/components/schemas/Budget"
- }
- },
- "description": "A type that defines the budget details for a Cost Per Click (CPC) Promoted Listings campaign."
- },
- "CampaignBudgetRequest": {
- "type": "object",
- "properties": {
- "daily": {
- "description": "The daily budget limit for a CPC Promoted Listings campaign.",
- "$ref": "#/components/schemas/BudgetRequest"
- }
- },
- "description": "A container for the details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model."
- },
- "CampaignCriterion": {
- "type": "object",
- "properties": {
- "autoSelectFutureInventory": {
- "type": "boolean",
- "description": "A field used to indicate whether listings shall be automatically added to, or removed from, a Promoted Listings campaign based on the rules that have been configured for the campaign.
If set to true, eBay adds all listings matching the campaign criterion to the campaign, including any new listings created from the items in a seller's inventory.
Default: false"
- },
- "criterionType": {
- "type": "string",
- "description": "This enum defines the criterion (selection rule) types. Currently, the only criterion type supported is INVENTORY_PARTITION, and you must specify this value if you manage your items with the Inventory API and you want to include items based on their inventory reference IDs.
Do not include this field if you manage your listings with Trading API/legacy model. For implementation help, refer to eBay API documentation"
- },
- "selectionRules": {
- "type": "array",
- "description": "This container shows all of the rules/inclusion filters used to add listings to the campaign. For information on using the contained fields, see Promoted Listing campaigns.",
- "items": {
- "$ref": "#/components/schemas/SelectionRule"
- }
- }
- },
- "description": "This type defines the fields for specifying the criterion (selection rule) settings of an ad campaign. If you populate the campaignCriterion object in your createCampaign request, ads for the campaign are created by rule for the listings that meet the criteria you specify, and these ads are associated with the newly created campaign."
- },
- "CampaignDTO": {
- "type": "object",
- "properties": {
- "audiences": {
- "type": "array",
- "description": "The audiences that the email campaign is being sent to. See AudienceTypeEnum for a list of audience types.",
- "items": {
- "$ref": "#/components/schemas/CampaignAudience"
- }
- },
- "creationDate": {
- "type": "string",
- "description": "The date and time that the email campaign was created, given in UTC format."
- },
- "emailCampaignId": {
- "type": "string",
- "description": "The unique eBay identifier for the email campaign assigned automatically when the email campaign is created."
- },
- "emailCampaignStatus": {
- "type": "string",
- "description": "The email campaign status. See EmailCampaignStatusEnum for information on statuses. For implementation help, refer to eBay API documentation"
- },
- "emailCampaignType": {
- "type": "string",
- "description": "The email campaign type. See CampaignTypeEnum for definitions of email campaign types. For implementation help, refer to eBay API documentation"
- },
- "marketplaceId": {
- "type": "string",
- "description": "The eBay marketplace where the email campaign is active."
- },
- "modificationDate": {
- "type": "string",
- "description": "The date and time the email campaign was last modified, given in UTC format."
- },
- "scheduleDate": {
- "type": "string",
- "description": "The date and time that the email campaign newsletter is scheduled to send, given in UTC format."
- },
- "scheduleDateType": {
- "type": "string",
- "description": "The schedule type used for sending the email campaign. See ScheduleDateTypeEnum for available schedule types. For implementation help, refer to eBay API documentation"
- },
- "sentDate": {
- "type": "string",
- "description": "The date and time that the email campaign was last sent, given in UTC format."
- },
- "subject": {
- "type": "string",
- "description": "The email campaign subject line.."
- }
- },
- "description": "email campaign instance body"
- },
- "CampaignPagedCollectionResponse": {
- "type": "object",
- "properties": {
- "campaigns": {
- "type": "array",
- "description": "This array contains all of the seller's campaign that match the request criteria.",
- "items": {
- "$ref": "#/components/schemas/Campaign"
- }
- },
- "href": {
- "type": "string",
- "description": "The URI of the current page of results from the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results.
Max length: 2048"
- },
- "total": {
- "type": "integer",
- "description": "The total number of campaigns retrieved in the result set.
If no campaigns are found, this field is returned with a value of 0.",
- "format": "int32"
- }
- },
- "description": "This type defines the fields that paginate the campaigns returned by the request. The entire result set consists of 0 or more sequenced response pages, where each page consists of 0 or more items from the complete result set."
- },
- "Campaigns": {
- "type": "object",
- "properties": {
- "campaigns": {
- "type": "array",
- "description": "This is an array of one or campaigns that match the listing or inventory item group specified in the request.",
- "items": {
- "$ref": "#/components/schemas/Campaign"
- }
- }
- },
- "description": "This type contains a list of campaigns."
- },
- "CloneCampaignRequest": {
- "type": "object",
- "properties": {
- "campaignName": {
- "type": "string",
- "description": "A seller-defined name for the newly-cloned campaign. This value must be unique for the seller. You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters"
- },
- "endDate": {
- "type": "string",
- "description": "The date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is omitted, the campaign will have no defined end date, and will not end until the seller makes a decision to end the campaign with an endCampaign call, or if they update the campaign at a later time with an end date."
- },
- "fundingStrategy": {
- "description": "This container is used to set the funding model and default bid percentage for the campaign to be cloned.",
- "$ref": "#/components/schemas/FundingStrategy"
- },
- "startDate": {
- "type": "string",
- "description": "The date and time the cloned campaign starts, in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller. On the date specified, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts after this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign. Call getCampaign to check the status of the campaign.
"
- }
- },
- "description": "This type defines the fields needed for a clone-campaign request."
- },
- "CouponConfiguration": {
- "type": "object",
- "properties": {
- "couponCode": {
- "type": "string",
- "description": "A unique code that buyers can use during checkout to receive a discount. The code must be unique across eBay.
The code must be from 8-15 alphanumeric characters and can contain no more than two dashes ( - ).
This is required when the promotion type is CODED_COUPON."
- },
- "couponType": {
- "type": "string",
- "description": "This indicates the type of Coded Coupon promotion, and is required when the promotion type is CODED_COUPON.
Supported types:- PRIVATE_SINGLE_SELLER_COUPON: Anyone can use and share the coupon code, but it isn't posted on eBay.
- PUBLIC_SINGLE_SELLER_COUPON: Anyone can find the coupon code on eBay and use it.
For implementation help, refer to eBay API documentation"
- },
- "maxCouponRedemptionPerUser": {
- "type": "integer",
- "description": "This sets the limit on the number of times a buyer can use this coupon. The range of values is 1-10. If no value is provided, a buyer can use the coupon an unlimited number of times.",
- "format": "int32"
- }
- },
- "description": "This container defines a coded coupon promotion. It is required if the promotion type is CODED_COUPON."
- },
- "CreateAdGroupRequest": {
- "type": "object",
- "properties": {
- "defaultBid": {
- "description": "A bid amount that applies to all of the keywords in an ad group that do not have individual bids.",
- "$ref": "#/components/schemas/Amount"
- },
- "name": {
- "type": "string",
- "description": "The seller-defined name of the ad group."
- }
- },
- "description": "A type that defines the fields for the CreateAdGroup request."
- },
- "CreateAdRequest": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model. Required if the campaign's funding model is Cost Per Click (CPC).
Create an ad group using the createAdGroup method.
Specify the campaign to associate the ad group with using the campaign_id path parameter.
Note: You can call the getAdGroups method to retrieve the ad group IDs for a seller."
- },
- "bidPercentage": {
- "type": "string",
- "description": "The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
Required if the campaign's funding model is Cost Per Sale (CPS).
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
This is default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.
Minimum value: 2.0
Maximum value: 100.0"
- },
- "listingId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a listing that is generated when the listing is created. Note: This field accepts listing IDs, as generated by the Inventory API, and item IDs, as used in the eBay Traditional API set (e.g., the Trading and Finding APIs).
"
- }
- },
- "description": "This type defines the fields for the create ad request."
- },
- "CreateAdsByInventoryReferenceRequest": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "Note: This field is not currently in use. Ad groups are only applicable to Promoted Listings Advanced (PLA) ad campaigns that use the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information."
- },
- "bidPercentage": {
- "type": "string",
- "description": "The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
Required if the campaign's funding model is Cost Per Sale (CPS).
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
This is default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.
Minimum value: 2.0
Maximum value: 100.0"
- },
- "inventoryReferenceId": {
- "type": "string",
- "description": "An ID that identifies a single-item listing or multiple-variation listing that is managed with the Inventory API. The inventory reference ID is a seller-defined value that can be either an SKU for a single-item listing or an inventoryItemGroupKey for a multiple-value listing.
An inventoryItemGroupKey is a value that the seller defines to indicate a listing that's the parent of an inventory item group (a multiple-variation listing, such as a listing for a shirt that's available in multiple sizes and colors).
You must always specify both an inventoryReferenceId and an inventoryReferenceType to indicate an item that's managed with the Inventory API.
"
- },
- "inventoryReferenceType": {
- "type": "string",
- "description": "Indicates the type of item the inventoryReferenceId references. The item can be either an INVENTORY_ITEM or INVENTORY_ITEM_GROUP. You must always pair an inventoryReferenceId with and inventoryReferenceType.
For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type defines the fields needed to create ads by inventory reference ID request."
- },
- "CreateAdsByInventoryReferenceResponse": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for an ad group in a Promoted Listings Advanced (PLA) campaign that uses the Cost Per Click (CPC) funding model.Note: This field will always be returned for campaigns that use the CPC funding model. It will not be returned for campaigns that use the Cost Per Sale (CPS) funding model."
- },
- "ads": {
- "type": "array",
- "description": "A list of ad IDs. An ad ID is generated for each successfully created ad.",
- "items": {
- "$ref": "#/components/schemas/AdReference"
- }
- },
- "errors": {
- "type": "array",
- "description": "An array of errors or warnings associated with the create-ads request.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "inventoryReferenceId": {
- "type": "string",
- "description": "An ID that identifies a single-item listing or multiple-variation listing that is managed with the Inventory API. The inventory reference ID is a seller-defined value that can be either an SKU for a single-item listing or an inventoryItemGroupKey for a multiple-value listing.
"
- },
- "inventoryReferenceType": {
- "type": "string",
- "description": "Indicates the type of item the inventoryReferenceId references. The item can be either an INVENTORY_ITEM or INVENTORY_ITEM_GROUP. For implementation help, refer to eBay API documentation"
- },
- "statusCode": {
- "type": "integer",
- "description": "An HTTP status code that indicates the response-status of the request. Check this code to see if the ads were successfuly created.",
- "format": "int32"
- }
- },
- "description": "This type defines the fields returned when you create an ad by inventory reference ID."
- },
- "CreateCampaignRequest": {
- "type": "object",
- "properties": {
- "budget": {
- "description": "The allocated daily budget for the Cost Per Click (CPC) Promoted Listings campaign.
Required if the campaign funding model is CPC.",
- "$ref": "#/components/schemas/CampaignBudgetRequest"
- },
- "campaignCriterion": {
- "description": "This container is used if the seller wishes to create one or more rules for a rules-based campaign. If you populate the campaignCriterion object in your createCampaign request, ads for the campaign are created by rule for the listings that meet the criteria you specify, and these ads are associated with the campaign to be created.",
- "$ref": "#/components/schemas/CampaignCriterion"
- },
- "campaignName": {
- "type": "string",
- "description": "A seller-defined name for the campaign. This value must be unique for the seller. You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters"
- },
- "endDate": {
- "type": "string",
- "description": "The date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is omitted, the campaign will have no defined end date, and will not end until the seller makes a decision to end the campaign with an endCampaign call, or if they update the campaign at a later time with an end date."
- },
- "fundingStrategy": {
- "description": "This container is used to set the funding model and default bid percentage for a Cost Per Sale (CPS) campaign.",
- "$ref": "#/components/schemas/FundingStrategy"
- },
- "marketplaceId": {
- "type": "string",
- "description": "The ID of the eBay marketplace where the campaign is hosted. See the MarketplaceIdEnum type to get the appropriate enumeration value for the listing marketplace. For implementation help, refer to eBay API documentation"
- },
- "startDate": {
- "type": "string",
- "description": "The date and time the campaign starts, in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller. On the date specified, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts after this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign. Call getCampaign to check the status of the campaign.
"
- }
- },
- "description": "This type defines the fields needed to create a campaign. To create a campaign, you need to specify a name, start and end dates, funding, marketplace, and optionally the criterion (selection rules)."
- },
- "CreateEmailCampaignRequest": {
- "type": "object",
- "properties": {
- "audienceCodes": {
- "type": "array",
- "description": "An array of audience codes for the audiences of the email campaign. At least one audience code is required. There is no upper limit to the number of audience codes.
To retrieve seller audiences, call getAudiences. Use the code values in the response to populate audienceCodes.",
- "items": {
- "type": "string"
- }
- },
- "categoryId": {
- "type": "string",
- "description": "The unique identifier of either an eBay category or a store category.
This field is used if a seller wants to apply an email campaign to a specific eBay category or store category. The categoryType determines whether the categoryId value is an eBay category or store category.
To retrieve eBay categories, use the getCategories or Taxonomy API. To retrieve seller store categories, use the getStore call. Use the categoryId value of the desired category from the results as the value in the request.
itemSelectMode must be set to AUTO in order to use a category ID."
- },
- "categoryType": {
- "type": "string",
- "description": "This field must be set when applying an email campaign to a specific eBay category or store category. The enumeration value used indicates which type of category the categoryId belongs to. For implementation help, refer to eBay API documentation"
- },
- "emailCampaignType": {
- "type": "string",
- "description": "The email campaign type. There are six email campaigns that a user can create:WELCOME - an email sent automatically to new subscribers.ITEM_SHOWCASE - an email featuring new products & collections that the seller wants to highlight.COUPON - an email containing a coupon code and up to 4 items that this coupon can be applied to.ORDER_DISCOUNT - an email containing an order discount and up to 10 items that this discount can be applied to.SALE_EVENT - an email about a sale event and up to 10 items that the sale can be applied to.VOLUME_PRICING - an email containing up to 10 items that are eligible for volume pricing.
emailCampaignType cannot be updated once the email campaign is created. For implementation help, refer to eBay API documentation"
- },
- "itemIds": {
- "type": "array",
- "description": "An array of unique identifiers for the listings displayed in an email campaign. Used if the seller wishes to select the eBay listings in the email campaign rather than have eBay automatically select them.
Call getSellerList to retrieve all seller listings. Each Item result contains an ItemID value. Use this value in itemIds to feature that listing.
The maximum number of itemIds for the COUPON campaign type is 4, and for every other campaign type is 10
itemSelectMode must be set to MANUAL in order to use this field.",
- "items": {
- "type": "string"
- }
- },
- "itemSelectMode": {
- "type": "string",
- "description": "Determines whether listings featured in an email campaign are selected by the seller or by eBay.
If itemSelectMode is set to AUTO, eBay automatically choses listings based on values set for sort, categoryType, categoryId, and priceRange.
If itemSelectMode is set to MANUAL, listings are set by the seller by populating the itemIds array.
Note: itemSelectMode is always set to AUTO for WELCOME email campaigns. For implementation help, refer to eBay API documentation"
- },
- "personalizedMessage": {
- "type": "string",
- "description": "The body of the email campaign. Accepts HTML and CSS. The maximum length is 1000 characters."
- },
- "priceRange": {
- "description": "This container is used if the seller wants to apply the email campaign to listings based on a price range.
The priceRange container consists of the currency, gte, and lte fields.
\"gte\" stands for \"greater than or equal to\" and \"lte\" stands for \"less than or equal to\". Either gte, lte, or both must be used.
currency is a required field if including a price range. One of the three-digit currency codes from CurrencyCodeEnum must be specified.
Note: Use this object when the itemSelectMode is set to AUTO.",
- "$ref": "#/components/schemas/PriceRange"
- },
- "promotionId": {
- "type": "string",
- "description": "The unique identifier of the promotion used for an email campaign if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT. promotionSelectModeEnum must set to MANUAL if a promotion is selected.
Call getPromotions to retrieve a list of the seller's promotions. Use the promotionId from an individual PromotionDetail in the result to populate the request."
- },
- "promotionSelectModeEnum": {
- "type": "string",
- "description": "The selection mode for the promotion used if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT.
If promotionSelectModeEnum is set to AUTO, eBay will choose the promotion to include in the email campaign. If set to MANUAL, the seller must specify the promotion in the promotionId field. For implementation help, refer to eBay API documentation"
- },
- "scheduleDate": {
- "type": "string",
- "description": "The date and time that the email campaign newsletter will be sent, given in UTC format. Example: 2023-05-20T03:13:35Z
This field should be used if the seller wishes to send the email campaign on a future date. If no scheduleDate is set, the email campaign will send once it is created or updated."
- },
- "sort": {
- "type": "string",
- "description": "The sort rule is used to display the listings featured in the email campaign.
Sort rules are only used if itemSelectMode is set to AUTO. If itemSelectMode is MANUAL, listings are displayed in the order in which they are listed in the itemIds array. The following sort rules are available:ENDING_FIRST displays listings by ending date, from soonest to latest.LOWEST_PRICED displays listings by price, from lowest to highest.HIGHEST_PRICED displays listings by price, from highest to lowest.NEWLY_LISTED displays listings by date listed, with the newest first.
The default sort rule is NEWLY_LISTED. For implementation help, refer to eBay API documentation"
- },
- "subject": {
- "type": "string",
- "description": "The email campaign subject. The maximum length is 70 characters."
- }
- },
- "description": "create email campaign request payload"
- },
- "CreateEmailCampaignResponse": {
- "type": "object",
- "properties": {
- "emailCampaignId": {
- "type": "string",
- "description": "The unique eBay-assigned identifier of the email campaign. It is generated automatically when the email campaign is created.
This value is returned unless there is an error."
- },
- "emailCampaignStatus": {
- "type": "string",
- "description": "The status of the email campaign.
ACTIVE is returned for email campaigns that have been successfully created but not been sent.
SENT is returned for email campaigns that have already been sent.
ERROR is returned when an email has not been successfully created. For implementation help, refer to eBay API documentation"
- }
- }
- },
- "CreateKeywordRequest": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "This adGroupId is created when an ad group is first created and associated with a campaign. This is the ad group that the corresponding keyword will be added to. This ad group must be a part of the campaign that is specified in the call URI.
Note: You can call the getAdGroups method to retrieve the ad group IDs for a seller, and getKeywords to retrieve the keyword IDs for a seller's keywords."
- },
- "bid": {
- "description": "This container is used to set the bid for the keyword. Each time a listing is retrieved in search results using this keyword and clicked on, the seller will be charged this amount. Each click goes toward the daily budget set up for the CPC campaign. If the bid is not provided, then the default bid associated with the ad group is used.
Note: You can call the suggestBids method to retrieve the suggested bids for keywords.",
- "$ref": "#/components/schemas/Amount"
- },
- "keywordText": {
- "type": "string",
- "description": "Input the keyword into this field."
- },
- "matchType": {
- "type": "string",
- "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A type that defines the fields for the CreateKeyword request."
- },
- "CreateNegativeKeywordRequest": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "This adGroupId is created when an ad group is first created and associated with a campaign. This is the ad group to which the corresponding negative keyword will be added.
Note: You can call the getAdGroups method to retrieve the ad group IDs for a seller.
Required if the negative keyword is being created at the ad group level."
- },
- "campaignId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created.
Required if the negative keyword is being created at the ad group level."
- },
- "negativeKeywordMatchType": {
- "type": "string",
- "description": "A field that defines the match type for the negative keyword.
Note: Broad matching of negative keywords is not currently supported.
Valid Values: For implementation help, refer to eBay API documentation"
- },
- "negativeKeywordText": {
- "type": "string",
- "description": "The negative keyword text."
- }
- },
- "description": "A type that defines the fields for the CreateNegativeKeyword request."
- },
- "CreateReportTask": {
- "type": "object",
- "properties": {
- "additionalRecords": {
- "type": "array",
- "description": "A list of additional records that shall be included in the report, such as non-performing data.
Note: Additional records are only applicable to Promoted Listings Advanced (PLA) campaigns that use the Cost Per Click (CPC) funding model.
Valid Value: NON_PERFORMING_DATA",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- },
- "campaignIds": {
- "type": "array",
- "description": "A list of campaign IDs to be included in the report task. Call getCampaigns to get a list of the current campaign IDs for a seller.
For Promoted Listings Standard (PLS) sellers, this field is required if the reportType is set to CAMPAIGN_PERFORMANCE_REPORT or CAMPAIGN_PERFORMANCE_SUMMARY_REPORT.
For Promoted Listings Advanced (PLA) sellers, leave this request field blank to retrieve the details for all campaigns associated with your account, or specify the campaign IDs for which you would like to retrieve the campaign-specific details.
Note: There is a maximum data limit that cannot be exceeded when generating reports. If this threshold is exceeded, the report will fail. Refer to Promoted Listings reporting in the Selling Integration Guide for details.
Maximum: 1,000 IDs (for PLA or PLS)
",
- "items": {
- "type": "string"
- }
- },
- "dateFrom": {
- "type": "string",
- "description": "The date defining the start of the timespan covered by the report.
Format the timestamp as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock with local offset.
Note: The date specified cannot be a future date.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2021-03-15T13:00:00-07:00"
- },
- "dateTo": {
- "type": "string",
- "description": "The date defining the end of the timespan covered by the report.
As with the dateFrom field, format the timestamp as an ISO 8601 string.
Note: The date specified cannot be a future date. Additionally, the time specified must be a later time than that specified in the dateFrom field.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2021-03-17T13:00:00-07:00"
- },
- "dimensions": {
- "type": "array",
- "description": "The list of the dimensions applied to the report. A dimension is an attribute to which the report data applies. For example, if you set dimensionKey to campaign_id in a Campaign Performance Report, the data will apply to the entire ad campaign. For information on the dimensions and how to specify them, see Promoted Listings reporting.
",
- "items": {
- "$ref": "#/components/schemas/Dimension"
- }
- },
- "fundingModels": {
- "type": "array",
- "description": "The funding model for the campaign that shall be included in the report.
Note: The default funding model for Promoted Listings reports is COST_PER_SALE.
Note: Multiple value support for the fundingModels array has been deprecated. See API Deprecation Status for information.
Valid Values:COST_PER_SALECOST_PER_CLICK
Required if the campaign funding model is Cost Per Click (CPC).",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- },
- "inventoryReferences": {
- "type": "array",
- "description": "You can use this field to supply an array of items to include in the report if you manage your inventory with the Inventory API.
This field is mutually exclusive with the listingIds field; if you populate this field, do not populate the listingIds field.
An inventory reference identifies an item in your inventory using a pair of values, where the inventoryReferenceId can be either a seller-defined SKU value or an inventoryItemGroupKey, where an inventoryItemGroupKey is seller-defined ID for an inventory item group (a multiple-variation listing).
Couple the inventoryReferenceId with an inventoryReferenceType identifier to fully identify an item in your inventory.
Maximum: 500 items
Required if you do not supply an array of listingId values or if you set reportType to INVENTORY_PERFORMANCE_REPORT.",
- "items": {
- "$ref": "#/components/schemas/InventoryReference"
- }
- },
- "listingIds": {
- "type": "array",
- "description": "Use this field to supply an array of listing IDs you want to include in the report.
A listing ID is the eBay listing identifier that is generated when the listing is created. This field accepts listing ID values generated with both the Inventory API and the eBay Traditional APIs, such as the Trading and Finding APIs.
Important: This field is mutually exclusive with the inventoryReferences field; if you populate this field, do not populate the inventoryReferences field.
For Promoted Listings Standard (PLS) sellers, this field is required if you do not supply an array of inventoryReferences values or if you set the reportType to LISTING_PERFORMANCE_REPORT.
For Promoted Listings Advanced (PLA) sellers, leave this field blank to retrieve the details for all listings associated with the specified campaign IDs (or all campaigns associated with your account, if no campaign IDs are specified), or specify the listing IDs for which you would like to retrieve the listing-specific details.
Note: There is a maximum data limit that cannot be exceeded when generating reports. If this threshold is exceeded, the report will fail. Refer to Promoted Listings reporting in the Selling Integration Guide for details.
Maximum: 500 listings",
- "items": {
- "type": "string"
- }
- },
- "marketplaceId": {
- "type": "string",
- "description": "The ID for the eBay marketplace on which the report is based.
Maximum: 1 For implementation help, refer to eBay API documentation"
- },
- "metricKeys": {
- "type": "array",
- "description": "The list of metrics to be included in the report. Metrics are the quantitative measurements compiled into the report and the data returned is based on the specified dimension of the report. For example, if the dimension is campaign, the metrics for number of sales would be the number of sales in the campaign. However, if the dimension is listing, the number of sales represents the number of items sold in that listing.
For information on metric keys and how to set them, see Promoted Listings reporting.
Minimum: 1",
- "items": {
- "type": "string"
- }
- },
- "reportFormat": {
- "type": "string",
- "description": "The file format of the report. Currently, the only supported format is TSV_GZIP, which is a gzip file with tab separated values. For implementation help, refer to eBay API documentation"
- },
- "reportType": {
- "type": "string",
- "description": "The type of report to be generated, such as ACCOUNT_PERFORMANCE_REPORT or CAMPAIGN_PERFORMANCE_REPORT.
Note: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending.
Maximum: 1 For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type defines the rules that govern the generation of a report task and the criteria that's used to create the report. The report-generation rules include the starting and ending dates for the report. Report-task criteria includes the report dimensions, metrics, listings covered in the report, and so on. For information on the required and optional fields for each report type, see Promoted Listings reporting."
- },
- "DeleteAdRequest": {
- "type": "object",
- "properties": {
- "listingId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a listing that is generated when the listing is created. Note: This request accepts both listing IDs, as generated by the Inventory API, and an item IDs, as used in the eBay Traditional API set (e.g., the Trading and Finding APIs).
"
- }
- },
- "description": "This type defines the fields used in a delete-ad request."
- },
- "DeleteAdResponse": {
- "type": "object",
- "properties": {
- "adId": {
- "type": "string",
- "description": "The unique identifier of the ad that was deleted, or the ad that the seller attempted to delete."
- },
- "errors": {
- "type": "array",
- "description": "An array of the errors or warnings associated with the request.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "listingId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a listing that is generated when the listing is created."
- },
- "statusCode": {
- "type": "integer",
- "description": "An HTTP status code that indicates the response-status of the request. Check this code to see if the ad was successfully deleted.Note:A status code is returned for each ad that the seller deletes, or attempts to delete.",
- "format": "int32"
- }
- },
- "description": "This type defines the fields returned in a delete-ad response."
- },
- "DeleteAdsByInventoryReferenceRequest": {
- "type": "object",
- "properties": {
- "inventoryReferenceId": {
- "type": "string",
- "description": "The inventory reference ID is a seller-defined SKU value for a single-item listing, or a seller-defined identifier for an inventory item group. Both of these values are defined when using the Inventory API, and an inventory item group is used to create a multiple-variation listing."
- },
- "inventoryReferenceType": {
- "type": "string",
- "description": "The enumeration value passed into this field indicates the type of value used for the corresponding inventoryReferenceId value. The enumeration value used here will either be INVENTORY_ITEM (to delete the ad for a single SKU listing) or INVENTORY_ITEM_GROUP (to delete the ad for a multiple-variation listing). For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type defines the fields needed to delete an ad by its inventory reference ID. You must always supply both inventory_reference_id and inventory_reference_type."
- },
- "DeleteAdsByInventoryReferenceResponse": {
- "type": "object",
- "properties": {
- "adIds": {
- "type": "array",
- "description": "The unique identifier of the ad that was deleted, or the ad that the seller attempted to delete.Note:Although the field name is plural and it is an array, only one ad ID will be returned here since there can be only one ad per listing.",
- "items": {
- "type": "string"
- }
- },
- "errors": {
- "type": "array",
- "description": "The container for the errors associated with the request.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "inventoryReferenceId": {
- "type": "string",
- "description": "The inventory reference ID is a seller-defined SKU value for a single-item listing, or a seller-defined identifier for an inventory item group. Both of these values are defined when using the Inventory API, and an inventory item group is used to create a multiple-variation listing."
- },
- "inventoryReferenceType": {
- "type": "string",
- "description": "The enumeration value returned here indicates if the ad was for a single-variation listing or a multiple-variation listing. For implementation help, refer to eBay API documentation"
- },
- "statusCode": {
- "type": "integer",
- "description": "An HTTP status code indicating if the corresponding ad was successfully deleted or not. 200 Successful should be returned for successfully deleted ads. Note:A status code is returned for each ad that the seller deletes, or attempts to delete.",
- "format": "int32"
- }
- },
- "description": "This type defines the fields returned by request to delete a set of ads by inventory reference ID."
- },
- "DeleteEmailCampaignResponse": {
- "type": "object",
- "properties": {
- "emailCampaignId": {
- "type": "string",
- "description": "The unique eBay-assigned ID for the email campaign that is generated when the email campaign is created."
- }
- }
- },
- "Dimension": {
- "type": "object",
- "properties": {
- "annotationKeys": {
- "type": "array",
- "description": "A list of annotations associated with the dimension of the report.",
- "items": {
- "type": "string"
- }
- },
- "dimensionKey": {
- "type": "string",
- "description": "The name of the dimension on which the report is based. A dimension is an attribute to which the report data applies.
"
- }
- },
- "description": "This type defines the annotation and dimension key used by the report. For information on how to set these values, see Promoted Listings reporting."
- },
- "DimensionKeyAnnotation": {
- "type": "object",
- "properties": {
- "annotationKey": {
- "type": "string",
- "description": "An annotation key associated with the dimension."
- },
- "dataType": {
- "type": "string",
- "description": "The data type of the annotation key value. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type defines the annotation values associated with a dimension. Annotations are metadata of the dimension. For example, annotations for a listing ID could be listing_title or listing_quantity_sold."
- },
- "DimensionMetadata": {
- "type": "object",
- "properties": {
- "dataType": {
- "type": "string",
- "description": "The data type of the dimension value used to create the report. For implementation help, refer to eBay API documentation"
- },
- "dimensionKey": {
- "type": "string",
- "description": "The name of the dimension used to create the report."
- },
- "dimensionKeyAnnotations": {
- "type": "array",
- "description": "An list of annotation keys associated with the specified dimension of the report.",
- "items": {
- "$ref": "#/components/schemas/DimensionKeyAnnotation"
- }
- }
- },
- "description": "This type defines the dimension used to create the report and the annotation keys associated with that dimension."
- },
- "DiscountBenefit": {
- "type": "object",
- "properties": {
- "amountOffItem": {
- "description": "The monetary amount that is discounted off an item (or items) when the promotion criteria is met.
For threshold promotions, where the buyer triggers the discount, the valid values for this field are:
5, 6, 7, 8, 9, 10, 15, 20, 25,
30, 35, 40, 45, 50, 55, 60, 65,
70, 75, 80, 85, 90, 95, 100, 110,
120, 125, 150, 200, 250
For markdown promotions, the range is greater, as outlined below and detailed more precisely here: - $1 increments from $5 to $100
- $5 increments from $105 to $1,000
- $100 increments from $1,100 to $15,000
",
- "$ref": "#/components/schemas/Amount"
- },
- "amountOffOrder": {
- "description": "Used for threshold promotions, this is the monetary amount that is discounted off an order when the promotion criteria is met. Because this field is valid only for orders, it's not a valid combination to use with markdown promotions.
Valid values for the associated amountOffOrder.value field:
5, 6, 7, 8, 9, 10, 15, 20, 25,
30, 35, 40, 45, 50, 55, 60, 65,
70, 75, 80, 85, 90, 95, 100, 110,
120, 125, 150, 200, 250",
- "$ref": "#/components/schemas/Amount"
- },
- "percentageOffItem": {
- "type": "string",
- "description": "The percentage applied to the sales price that is discounted off the promoted item (or items) when the promotion criteria is met.
Valid integer values for percentage off: Min: 5 Max: 80"
- },
- "percentageOffOrder": {
- "type": "string",
- "description": "Used for threshold promotions, this is the percentage of the order price that is discounted off the order when the promotion criteria is met. This field is not value for markdown promotions.
Valid integer values for ORDER_DISCOUNT promotions: Min: 5 Max: 80
For VOLUME_DISCOUNT promotions: Must be set to 0 for the first discount rule."
- }
- },
- "description": "This container defines the promotional discount as either a monetary amount or a percentage of the sales price. Important!: You must populate one and only one of the fields in this container:
- amountOffItem
- amountOffOrder
- percentageOffItem
- percentageOffOrder
Tip: Refer to Configuring discounts for threshold promotions for information and examples on how to combine discountBenefit and discountSpecification values to create different types of promotions.
"
- },
- "DiscountRule": {
- "type": "object",
- "properties": {
- "discountBenefit": {
- "description": "This container defines the promotional discount as either a monetary amount or a percentage of the sales price. Note: When configuring promotion benefits, populate just one of the following fields in the discountBenefit container:
- amountOffItem
- amountOffOrder
- percentageOffItem
- percentageOffOrder
For volume pricing, only percentageOffOrder is applicable as a discountBenefit. Also, the first discountBenefit container in a volume pricing configuration must set percentageOffOrder to 0.
Tip: Refer to Configuring discounts for threshold promotions for information and examples on how to combine discountBenefit and discountSpecification to create different types of promotions.
",
- "$ref": "#/components/schemas/DiscountBenefit"
- },
- "discountSpecification": {
- "description": "This container defines the criteria for when the discounts of a promotion trigger, such as the minimum quantity that the buyer must purchase before the promotion kicks in. The promotional discount is applied each time the criteria defined by this container is met. When configuring the rules that govern when the discounts are applied, populate just one of the following fields in the discountSpecification container:
- minAmount
- minQuantity
- forEachQuantity
- forEachAmount
Important: When configuring volume pricing promotions, only minQuantity is applicable as a discountSpecification. Also, the configuration for minQuantity in a volume pricing configuration is specific. In the first discountSpecification container, set minQuantity to 1, and in the second, set minQuantity to 2. If you include a third discountRules pair, minQuantity must be set to 3, and in a fourth, it must be set to 4. Also, you must set a ruleOrder value in each discountRules container. In the first container, discountRules must be set to 1, and in each subsequent container, the value be be incremented by 1. For more, see Configuring volume pricing discounts.
Tip: see Configuring discounts for threshold promotions for information and examples on how to combine discountBenefit and discountSpecification to create different types of promotions.
",
- "$ref": "#/components/schemas/DiscountSpecification"
- },
- "maxDiscountAmount": {
- "description": "The limit on how much a buyer can save using a CODED_COUPON promotion type. Permitted values are 1-1000. Supported currency codes include USD, GBP, EUR, and AUD. Note: The Currency Code for 'maxDiscountAmount' must be the same as the Currency Code for 'budget'.
",
- "$ref": "#/components/schemas/Amount"
- },
- "ruleOrder": {
- "type": "integer",
- "description": "This field indicates the order in which the discountRules are presented. The value specified for this field must equal the associated minQuantity value.
Required if you are creating a volume pricing promotion.",
- "format": "int32"
- }
- },
- "description": "This complex type defines a promotion as being either a monetary amount or a percentage of a sales price that's subtracted from the price of an item or order. Set the amount of the discount and the rules that govern when the discount triggers using the discountBenefit and discountSpecification fields.
Note: In volume pricing promotions, you must configure at least two discountRule containers and at most four.
"
- },
- "DiscountSpecification": {
- "type": "object",
- "properties": {
- "forEachAmount": {
- "description": "The monetary amount that must be spent on promoted items before the promotional discount is applied.
Valid values for the associated forEachAmount.value field:
5, 10, 15, 20, 25, 30, 35, 40, 45, 49,
50, 55, 59, 60, 65, 69, 70, 75, 79, 80,
85, 89, 90, 95, 99, 100, 110, 120, 125,
149, 150, 175, 199, 200, 249, 250, 299,
300, 350, 399, 400, 450, 499, 500",
- "$ref": "#/components/schemas/Amount"
- },
- "forEachQuantity": {
- "type": "integer",
- "description": "The number of items that must be purchased in order to qualify for the discount.
Valid values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
12, 13, 14, 15, 16, 17, 18, 19
20, 25, 50, 75, 100",
- "format": "int32"
- },
- "minAmount": {
- "description": "Known as the \"threshold amount\", the minimum dollar amount that needs to be spent on promoted items in order to qualify for the promotion's discount.
Valid values for the associated minAmount.value field:
5, 10, 15, 20, 25, 30, 35, 40, 45, 49,
50, 55, 59, 60, 65, 69, 70, 75, 79, 80,
85, 89, 90, 95, 99, 100, 110, 120,
125, 149, 150, 175, 199, 200, 249, 250, 299,
300, 350, 399, 400, 450, 499, 500",
- "$ref": "#/components/schemas/Amount"
- },
- "minQuantity": {
- "type": "integer",
- "description": "The minimum quantity of promoted items that needs to be bought in order to qualify for the promotion's discount.
Valid values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
12, 13, 14, 15, 16, 17, 18, 19
20, 25, 50, 75, 100",
- "format": "int32"
- },
- "numberOfDiscountedItems": {
- "type": "integer",
- "description": "Use this field to configure \"Buy One Get One\" (or BOGO) promotions.
You must couple this field with forEachQuantity and an amountOffItem or percentOffItem field to configure your BOGO promotion. This field is not valid with order-based promotions.
The value of this field represents the number of items to be discounted when other promotion criteria is met. For example, when the buyer adds the number of items identified by the forEachQuantity value to their cart, they are then eligible to receive the stated discount from an additional number of like items (the number of which is identified by this field) when they add those items to their cart. To receive the discount, the buyer must purchase the number of items indicated by forEachQuantity plus the number indicated by this field.
Valid values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10",
- "format": "int32"
- }
- },
- "description": "This container defines the criteria for when the discounts of a promotion trigger, such as the minimum quantity the buyer must purchase before the promotion kicks in. The promotional discount is applied each time the criteria defined by this container is met. Note: When configuring the rules that govern when the discounts are applied, populate just one of the following fields in the discountSpecification container:
- minAmount
- minQuantity
- forEachQuantity
- forEachAmount
Tip: Refer to Configuring discounts for threshold promotions for information and examples on how to combine discountBenefit and discountSpecification to create different types of promotions.
"
- },
- "DynamicAdRatePreference": {
- "type": "object",
- "properties": {
- "adRateAdjustmentPercent": {
- "type": "string",
- "description": "The percentage above or below (-) the eBay suggested ad rate that a seller is willing to pay.
This specifies the maximum and minimum values to which an ad rate can be dynamically adjusted."
- },
- "adRateCapPercent": {
- "type": "string",
- "description": "The maximum value (specified as a percentage) to which the eBay suggested ad rate can be adjusted. The adjusted ad rate will never exceed this percentage."
- }
- },
- "description": "A type that defines the ad rate details for a Promoted Listings Standard (PLS) ad campaign."
- },
- "Error": {
- "type": "object",
- "properties": {
- "category": {
- "type": "string",
- "description": "The category type for this error or warning. It takes an ErrorCategory object which can have one of three values:Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as \"Seller does not ship item to Antarctica\" or \"Buyer ineligible to purchase an alcoholic item\". Business errors are not syntactical input errors.Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.
"
- },
- "domain": {
- "type": "string",
- "description": "Name of the domain containing the service or application."
- },
- "errorId": {
- "type": "integer",
- "description": "A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.",
- "format": "int32"
- },
- "inputRefIds": {
- "type": "array",
- "description": "Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.",
- "items": {
- "type": "string"
- }
- },
- "longMessage": {
- "type": "string",
- "description": "An expanded version of message that should be around 100-200 characters long, but is not required to be such."
- },
- "message": {
- "type": "string",
- "description": "An end user and app developer friendly device agnostic message. It explains what the error or warning is, and how to fix it (in a general sense). Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale."
- },
- "outputRefIds": {
- "type": "array",
- "description": "Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.",
- "items": {
- "type": "string"
- }
- },
- "parameters": {
- "type": "array",
- "description": "This optional complex field type contains a list of one or more context-specific ErrorParameter objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.",
- "items": {
- "$ref": "#/components/schemas/ErrorParameter"
- }
- },
- "subdomain": {
- "type": "string",
- "description": "Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain."
- }
- },
- "description": "A container that defines the elements of error and warning messages."
- },
- "ErrorParameter": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "Name of the entity that threw the error."
- },
- "value": {
- "type": "string",
- "description": "A description of the error."
- }
- },
- "description": "Container for a error parameter."
- },
- "FundingStrategy": {
- "type": "object",
- "properties": {
- "adRateStrategy": {
- "type": "string",
- "description": "The ad rate strategy that shall be applied to the campaign. For implementation help, refer to eBay API documentation"
- },
- "bidPercentage": {
- "type": "string",
- "description": "The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
This is the default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.
Note:This field is only relevant for campaigns that use the CPS funding model and a fixed ad rate. It is not used for campaigns that use the Cost Per Click (CPC) funding model and should not be provided when the selected adRateStrategy for the campaign is dynamic.
Minimum value: 2.0
Maximum value: 100.0"
- },
- "dynamicAdRatePreferences": {
- "type": "array",
- "description": "A field that indicates whether a single, user-defined bid percentage (also known as the ad rate) should be used, or whether eBay should automatically adjust listings to maintain the daily suggested bid percentage.
Note: Dynamic adjustment is only applicable when the adRateStrategy is set to DYNAMIC.
Default: FIXED",
- "items": {
- "$ref": "#/components/schemas/DynamicAdRatePreference"
- }
- },
- "fundingModel": {
- "type": "string",
- "description": "Indicates the model that eBay uses to calculate the Promoted Listings fee. For a description of the funding model types, refer to FundingModelTypeEnum. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type defines how the Promoted Listings fee is calculated for a Promoted Listings ad campaign."
- },
- "GetEmailCampaignAudiencesResponse": {
- "type": "object",
- "properties": {
- "audiences": {
- "type": "array",
- "description": "An array of audiences available for the specified email campaign type. If no audiences are available, the result will return an empty array.",
- "items": {
- "$ref": "#/components/schemas/CampaignAudience"
- }
- },
- "href": {
- "type": "string",
- "description": "The URL to the current page of store email campaign audiences."
- },
- "limit": {
- "type": "integer",
- "description": "The value of the limit parameter submitted in the request, which is the maximum number of store email campaign audiences to return on a page from the result set.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
- },
- "offset": {
- "type": "integer",
- "description": "This value indicates the offset used for the current page of store email campaign audiences returned.",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The URI for the previous page of results. This is returned if there is a previous page of results from the result set."
- },
- "total": {
- "type": "integer",
- "description": "The total number of available audiences returned under the query conditions.",
- "format": "int32"
- }
- }
- },
- "GetEmailCampaignResponse": {
- "type": "object",
- "properties": {
- "audiences": {
- "type": "array",
- "description": "An array of one or more audiences associated with the email campaign.",
- "items": {
- "$ref": "#/components/schemas/CampaignAudience"
- }
- },
- "categoryId": {
- "type": "string",
- "description": "The unique identifier of an eBay category or an eBay store category. This field is returned if a seller has applied the email campaign to a specific category.
The categoryType value will indicate if the category ID is for an eBay category or an eBay store category."
- },
- "categoryType": {
- "type": "string",
- "description": "The enumeration value returned here indicates if the categoryId value is the identifier of an eBay category or an eBay store category.
This field is returned if a seller has applied the email campaign to a specific category. For implementation help, refer to eBay API documentation"
- },
- "creationDate": {
- "type": "string",
- "description": "The date and time that the email campaign was created, given in UTC format."
- },
- "emailCampaignId": {
- "type": "string",
- "description": "The unique identifier of the email campaign."
- },
- "emailCampaignStatus": {
- "type": "string",
- "description": "The email campaign status. See EmailCampaignStatusEnum for a list of valid statuses. For implementation help, refer to eBay API documentation"
- },
- "emailCampaignType": {
- "type": "string",
- "description": "The email campaign type. See CampaignTypeEnum for valid email campaign types. For implementation help, refer to eBay API documentation"
- },
- "itemIds": {
- "type": "array",
- "description": "The listing IDs of the items that were manually added to the email campaign.
Only listings added manually by the seller are returned. Returns a null array if no listings were added.",
- "items": {
- "type": "string"
- }
- },
- "itemSelectMode": {
- "type": "string",
- "description": "The mode used to select the items listed in the email campaign. For implementation help, refer to eBay API documentation"
- },
- "marketplaceId": {
- "type": "string",
- "description": "The eBay marketplace where the email campaign is active. See MarketplaceIdEnum for a list of marketplace IDs."
- },
- "modificationDate": {
- "type": "string",
- "description": "The date and time the email campaign was last modified, given in UTC format."
- },
- "personalizedMessage": {
- "type": "string",
- "description": "The body of the email campaign sent to the audience."
- },
- "priceRange": {
- "description": "The price range and currency set within the email campaign. This container will only return if a price range was set.",
- "$ref": "#/components/schemas/PriceRange"
- },
- "promotionId": {
- "type": "string",
- "description": "The ID of the promotion that was assigned to the email campaign."
- },
- "promotionSelectMode": {
- "type": "string",
- "description": "Indicates whether the listings that the promotion was applied to were selected manually or automatically.
This field will only return if a promotion was applied. For implementation help, refer to eBay API documentation"
- },
- "scheduleDate": {
- "type": "string",
- "description": "The date and time that the email campaign newsletter is scheduled to send, given in UTC format. This field is only returned if the seller set the start of the email campaign to a date in the future."
- },
- "scheduleDateType": {
- "type": "string",
- "description": "The schedule type of the email campaign. See ScheduleDateTypeEnum. For implementation help, refer to eBay API documentation"
- },
- "sentDate": {
- "type": "string",
- "description": "The date and time that the email campaign was sent, given in UTC format."
- },
- "sort": {
- "type": "string",
- "description": "The sort rule is used to display the items in the email campaign. If no sort rule was selected, the default will be NEWLY_LISTED. For implementation help, refer to eBay API documentation"
- },
- "subject": {
- "type": "string",
- "description": "The email campaign subject."
- }
- }
- },
- "GetEmailCampaignsResponse": {
- "type": "object",
- "properties": {
- "campaigns": {
- "type": "array",
- "description": "A list of email campaigns that match the search criteria.",
- "items": {
- "$ref": "#/components/schemas/CampaignDTO"
- }
- },
- "href": {
- "type": "string",
- "description": "The URL to the current page of store email campaigns."
- },
- "limit": {
- "type": "integer",
- "description": "The value of the limit parameter submitted in the request, which is the maximum number of store email campaigns to return on a page from the result set.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
- },
- "offset": {
- "type": "integer",
- "description": "This value indicates the offset used for current page of store email campaigns being returned.",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The URI for the previous page of results. This is returned if there is a previous page of results from the result set."
- },
- "total": {
- "type": "integer",
- "description": "Total number of available results returned under the filter criteria submitted in the request.",
- "format": "int32"
- }
- }
- },
- "GetEmailPreviewResponse": {
- "type": "object",
- "properties": {
- "content": {
- "type": "string",
- "description": "The raw HTML code of the email campaign contents. The client side can use this HTML output directly.
Because the contents of an email campaign are subject to change, these contents are a \"snapshot\" of the email campaign at a specific time and date, indicated by the renderDate field."
- },
- "renderDate": {
- "type": "string",
- "description": "The date and time when a \"snapshot\" of the email campaign contents contained in the content result was taken. Given in UTC format."
- }
- }
- },
- "GetEmailReportResponse": {
- "type": "object",
- "properties": {
- "clickCount": {
- "type": "integer",
- "description": "The number of item listing links clicked from the body of campaign emails for the time range specified by the query.",
- "format": "int32"
- },
- "openCount": {
- "type": "integer",
- "description": "The total email opened count for all email campaigns from a seller for the time range specified by the query.",
- "format": "int32"
- },
- "totalSales": {
- "description": "A seller's total sale amount for the time range specified by the query.",
- "$ref": "#/components/schemas/Amount"
- }
- }
- },
- "InventoryCriterion": {
- "type": "object",
- "properties": {
- "inventoryCriterionType": {
- "type": "string",
- "description": "Indicates how the items to include in the promotion are selected. You can include inventory by ID, using rules, or globally include all your inventory. For implementation help, refer to eBay API documentation"
- },
- "inventoryItems": {
- "type": "array",
- "description": "An array of containers for the seller's inventory reference IDs (also known as an \"SKU\" or \"custom label\") to be added to the promotion.
Note: The request can have either inventoryItems or listingIds, but not both.
Required: All listings in a promotion must offer an electronic payment method.
Maximum: 500 parent items
Maximum SKU or custom label length: 50 characters
Required if InventoryCriterionType is set to INVENTORY_BY_VALUE, you must specify either inventoryItems or listingIds.",
- "items": {
- "$ref": "#/components/schemas/InventoryItem"
- }
- },
- "listingIds": {
- "type": "array",
- "description": "An array of eBay listing IDs to be added to the promotion. Note: The request can have either inventoryItems or listingIds, but not both.
Required: All listings in a promotion must offer an electronic payment method.
Maximum: 500 parent items
Maximum SKU or custom label length: 50 characters
Required if InventoryCriterionType is set to INVENTORY_BY_VALUE, you must specify either inventoryItems or listingIds.",
- "items": {
- "type": "string"
- }
- },
- "ruleCriteria": {
- "description": "This container defines a set of inventory selection rules for a promotion.
When defining rule criteria, you must limit item exclusions to 100 IDs when you choose from live inventory.
Required if InventoryCriterionEnum is set to INVENTORY_BY_RULE or INVENTORY_ANY.",
- "$ref": "#/components/schemas/RuleCriteria"
- }
- },
- "description": "This type defines either the selections rules or the list of listing IDs for the promotion. The \"listing IDs\" are are either the seller's item IDs or the eBay listing IDs."
- },
- "InventoryItem": {
- "type": "object",
- "properties": {
- "inventoryReferenceId": {
- "type": "string",
- "description": "The seller's inventory reference ID for a listing. Also known as the \"SKU\" or \"custom label,\" an inventory reference ID is either the ID of the listing or, if the listing has variations (such as a shirt that's available in multiple sizes and colors), the ID of the parent listing."
- }
- },
- "description": "This type defines the fields for the seller inventory reference IDs (also known as an \"SKU\" or \"custom label\")."
- },
- "InventoryReference": {
- "type": "object",
- "properties": {
- "inventoryReferenceId": {
- "type": "string",
- "description": "The seller's inventory reference ID for an item that is managed with the Inventory API.
An inventory reference is either the ID of a single listing or the ID of the parent of an item group listing (a multi-variation listing, such as a shirt that is available in multiple sizes and colors).
Required if if you supply an inventoryReferenceType."
- },
- "inventoryReferenceType": {
- "type": "string",
- "description": "Indicates the type of item indicated by the inventoryReferenceId.
This value can be set to either INVENTORY_ITEM or INVENTORY_ITEM_GROUP (if the ID points to a multi-variation listing).
Required if if you supply an inventoryReferenceId. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This complex type is used to identify an item that is managed by the Inventory API. The type defines the fields contained in an inventory reference ID."
- },
- "ItemBasis": {
- "type": "object",
- "properties": {
- "estimatedValue": {
- "type": "integer",
- "description": "The estimated value of the search impressions for items based on the provided dimensions.
Duration: 17 days
Total slots: 200
Channel: Dweb, Mweb, Native",
- "format": "int32"
- },
- "metric": {
- "type": "string",
- "description": "The basis of the statistics. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A container for details regarding the basis for an item."
- },
- "ItemMarkdownStatus": {
- "type": "object",
- "properties": {
- "listingMarkdownStatus": {
- "type": "string",
- "description": "Indicates the state assigned to the markdown promotion using one of the status values. For implementation help, refer to eBay API documentation"
- },
- "statusChangedDate": {
- "type": "string",
- "description": "Identifies the date the last time the state of the promotion changed. Both both markdown and markup events can trigger a status change."
- },
- "statusMessage": {
- "type": "string",
- "description": "An eBay-assigned text string that describes the status of the promotion."
- }
- },
- "description": "This type defines the status of a markdown promotion."
- },
- "ItemPriceMarkdown": {
- "type": "object",
- "properties": {
- "applyFreeShipping": {
- "type": "boolean",
- "description": "If set to true, free shipping is applied to the first shipping service specified for the item. The first domestic shipping option is set to \"free shipping,\" regardless if the shipping optionType for that service is set to FLAT_RATE, CALCULATED, or NOT_SPECIFIED (freight). This flag essentially adds free shipping as a promotional bonus.
Default: false"
- },
- "autoSelectFutureInventory": {
- "type": "boolean",
- "description": "If set to true, eBay will automatically add inventory items to the markdown promotion if they meet the selectedInventoryDiscounts criteria specified for the markdown promotion.
Default: false"
- },
- "blockPriceIncreaseInItemRevision": {
- "type": "boolean",
- "description": "If set to true, price increases (including removing the free shipping flag) are blocked and an error message is returned if a seller attempts to adjust the price of an item that's partaking in this markdown promotion. If set to false, an item is dropped from the markdown promotion if the seller adjusts the price.
Default: false"
- },
- "description": {
- "type": "string",
- "description": "This field is required if you are configuring an MARKDOWN_SALE promotion.
This is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\" A tag line appears under the \"offer-type text\" that is generated for the promotion. The text is displayed on the offer tile that is shown on the seller's All Offers page and on the event page for the promotion. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. This text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"20% off\".
Maximum length: 50"
- },
- "endDate": {
- "type": "string",
- "description": "The date and time the promotion ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). The value supplied for endDate must be at least 24 hours after the value supplied for the startDate of the markdown promotion.
For display purposes, convert this time into the local time of the seller.
Max value:14 days for the AT, CH, DE, ES, FR, IE, IT, and UK, marketplaces.45 days for all other marketplaces.
"
- },
- "marketplaceId": {
- "type": "string",
- "description": "The eBay marketplace ID of the site where the markdown promotion is hosted. Markdown promotions are supported on all eBay marketplaces. For implementation help, refer to eBay API documentation"
- },
- "name": {
- "type": "string",
- "description": "The seller-defined name or 'title' of the promotion that the seller can use to identify a promotion. This label is not displayed in end-user flows.
Maximum length: 90"
- },
- "priority": {
- "type": "string",
- "description": "This field is ignored in markdown promotions. For implementation help, refer to eBay API documentation"
- },
- "promotionImageUrl": {
- "type": "string",
- "description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT promotions, populate this field with a URL that points to an image to be used with the promotion. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
- },
- "promotionStatus": {
- "type": "string",
- "description": "The current status of the promotion. When creating a new promotion, you must set this value to either DRAFT or SCHEDULED.
Note that you must set this value to SCHEDULED when you update a RUNNING promotion. For implementation help, refer to eBay API documentation"
- },
- "selectedInventoryDiscounts": {
- "type": "array",
- "description": "A list that defines the sets of selected items for the markdown promotion and the discount specified for promotion.",
- "items": {
- "$ref": "#/components/schemas/SelectedInventoryDiscount"
- }
- },
- "startDate": {
- "type": "string",
- "description": "The date and time the promotion starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
- }
- },
- "description": "This type defines the fields used to describe an item price markdown promotion."
- },
- "ItemPromotion": {
- "type": "object",
- "properties": {
- "applyDiscountToSingleItemOnly": {
- "type": "boolean",
- "description": "This flag is relevant in only when promotionType is set to VOLUME_DISCOUNT. For details on volume pricing promotions, see Configuring volume pricing discounts.
If set to true, the discount is applied only when the buyer purchases multiple quantities of a single item in the promotion. Otherwise, the promotional discount applies to multiple quantities of any items in the promotion. Different variations of a multi-variation item are considered to be the same item. Note that this flag is not relevant if the inventoryCriterion container identifies a single listing ID for the promotion."
- },
- "budget": {
- "description": "This sets the budget for the CODED_COUPON promotion type. Supported values range from 100-1000000. Supported currency codes include USD, GBP, EUR, and AUD. Note: The budget value for an active or paused promotion can not be decreased.
Note: The Currency Code for 'budget' must be the same as the Currency Code for 'maxDiscountAmount'.
",
- "$ref": "#/components/schemas/Amount"
- },
- "couponConfiguration": {
- "description": "The configuration of a coded coupon promotion.",
- "$ref": "#/components/schemas/CouponConfiguration"
- },
- "description": {
- "type": "string",
- "description": "This is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\"
The tag line appears under the \"offer-type text\" that is generated for the promotion and is displayed on the offer tile that's shown on the seller's All Offers page, and on the event page for the promotion. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. The offer-type text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"Extra 20% off when you buy 3+\".
Maximum length: 50
Required if you are configuring CODED_COUPON, ORDER_DISCOUNT, or MARKDOWN_SALE promotions (and not valid for VOLUME_DISCOUNT promotions)."
- },
- "discountRules": {
- "type": "array",
- "description": "This container defines a promotion using the following two required fields: - discountBenefit – Defines a discount as either a monetary amount or a percentage that is subtracted from the sales price of an item, a set of items, or an order.
- discountSpecification – Defines a set of rules that determine when the promotion is applied.
Note: For volume pricing, you must specify at least two and not more than four discountBenefit/discountSpecification pairs. In addition, you must define each set of rules with a ruleOrder value that corresponds with the order of volume discounts you present.
Tip: Refer to Specifying item promotion discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of promotions.
",
- "items": {
- "$ref": "#/components/schemas/DiscountRule"
- }
- },
- "endDate": {
- "type": "string",
- "description": "The date and time the promotion ends in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
- },
- "inventoryCriterion": {
- "description": "A container that defines either the listing IDs or the selection rules that specify the items to include in the promotion. Listing IDs can be either eBay listing IDs or a list of the seller's inventory reference IDs (know as SKUs or custom labels). See the selectionRules container for the rule criteria you can use to select inventory. Note: All listings in Promotions Manager promotions must support an electronic payment method.
",
- "$ref": "#/components/schemas/InventoryCriterion"
- },
- "marketplaceId": {
- "type": "string",
- "description": "The eBay marketplace ID of the site where the threshold promotion is hosted. Threshold promotions are currently supported on a limited number of eBay marketplaces. Valid values:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
For implementation help, refer to eBay API documentation"
- },
- "name": {
- "type": "string",
- "description": "The seller-defined name or \"title\" of the promotion that the seller can use to identify a promotion. This label is not displayed in end-user flows.
Maximum length: 90"
- },
- "priority": {
- "type": "string",
- "description": "Applicable for only ORDER_DISCOUNT promotions, this field indicates the precedence of the promotion, which is used to determine the position of a promotion on the seller's All Offers page. If an item is associated with multiple promotions, the promotion with the higher priority takes precedence. For implementation help, refer to eBay API documentation"
- },
- "promotionImageUrl": {
- "type": "string",
- "description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT promotions, and not valid for VOLUME_DISCOUNT promotions.
Populate this field with a URL that points to an image to be used with the promotion. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
- },
- "promotionStatus": {
- "type": "string",
- "description": "The current status of the promotion. When creating a new promotion, this value must be set to either DRAFT or SCHEDULED.
Note that you must set this value to SCHEDULED when you update a RUNNING promotion. For implementation help, refer to eBay API documentation"
- },
- "promotionType": {
- "type": "string",
- "description": "Use this field to specify the type of the promotion you are creating. The supported types are:
CODED_COUPON – A coupon code promotion set with createItemPromotion.MARKDOWN_SALE – A markdown promotion set with createItemPriceMarkdownPromotion.ORDER_DISCOUNT – A threshold promotion set with createItemPromotion.VOLUME_DISCOUNT – A volume pricing promotion set with createItemPromotion.
See the Promotions Manager documentation for details.
Required if you are creating a volume pricing promotion (VOLUME_DISCOUNT).
For implementation help, refer to eBay API documentation"
- },
- "startDate": {
- "type": "string",
- "description": "The date and time the promotion starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
- }
- },
- "description": "This type defines the fields that describe a threshold promotion and includes the promotional discount, the items included in the promotion, and the rules that specify when the promotion is applied."
- },
- "ItemPromotionResponse": {
- "type": "object",
- "properties": {
- "applyDiscountToSingleItemOnly": {
- "type": "boolean",
- "description": "If set to true, the discount is applied only when the buyer purchases multiple quantities of a single item in the promotion. Otherwise, the promotional discount applies to multiple quantities of any items in the promotion. Different variations of a multi-variation item are considered to be the same item. Note that this flag is not relevant if the inventoryCriterion container identifies a single listing ID for the promotion."
- },
- "budget": {
- "description": "This sets the budget for the CODED_COUPON promotion type. Supported values range from 100-1000000. Supported currency codes include USD, GBP, EUR, and AUD. Note: The budget value for an active or paused promotion can not be decreased.
Note: The Currency Code for 'budget' must be the same as the Currency Code for 'maxDiscountAmount'.
",
- "$ref": "#/components/schemas/Amount"
- },
- "couponConfiguration": {
- "description": "The configuration of a coded coupon promotion.",
- "$ref": "#/components/schemas/CouponConfiguration"
- },
- "description": {
- "type": "string",
- "description": "Required for CODED_COUPON promotions, this is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\" The tag line appears under the \"offer-type text\" that is generated for the promotion and is displayed under the offer tile that is shown on the seller's All Offers page and on the event page for the promotion. This tag line is not used with volume pricing promotions. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. This text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"Extra 20% off when you buy 3+\".
Maximum length: 50"
- },
- "discountRules": {
- "type": "array",
- "description": "A list containing the promotion benefits (discountRule) and the rules that define when the benefit is applied (discountSpecification).",
- "items": {
- "$ref": "#/components/schemas/DiscountRule"
- }
- },
- "endDate": {
- "type": "string",
- "description": "The date and time the promotion ends in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
- },
- "inventoryCriterion": {
- "description": "Returns either an array of listing IDs or the selection rules used to specify the items included in the promotion. Listing IDs can be either eBay listing IDs or an array of seller's inventory reference IDs (know as SKUs or custom labels). See the selectionRules container for the rule criteria you can use to select inventory.",
- "$ref": "#/components/schemas/InventoryCriterion"
- },
- "marketplaceId": {
- "type": "string",
- "description": "The eBay marketplace ID of the site where the threshold promotion is hosted. Threshold promotions are currently supported on a limited number of eBay marketplaces. Valid values:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
For implementation help, refer to eBay API documentation"
- },
- "name": {
- "type": "string",
- "description": "The seller-defined name or \"title\" of the promotion that the seller can use to identify a promotion. This label is not displayed in end-user flows.
Maximum length: 90"
- },
- "priority": {
- "type": "string",
- "description": "Applicable for only ORDER_DISCOUNT promotions, this field indicates the precedence of the promotion, which eBay uses to determine the position of a promotion on the seller's All Offers page. If an item is associated with multiple promotions, the promotion with the higher priority takes precedence. For implementation help, refer to eBay API documentation"
- },
- "promotionId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for the promotion that's generated when the promotion is created."
- },
- "promotionImageUrl": {
- "type": "string",
- "description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT promotions, and not applicable for VOLUME_DISCOUNT promotions, this field is a URL that points to an image for the promotion. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
- },
- "promotionStatus": {
- "type": "string",
- "description": "The current status of the promotion. When creating a new promotion, this value must be set to either DRAFT or SCHEDULED. For implementation help, refer to eBay API documentation"
- },
- "promotionType": {
- "type": "string",
- "description": "Indicates the type of the promotion, either CODED_COUPON, MARKDOWN_SALE, ORDER_DISCOUNT, or VOLUME_DISCOUNT. For implementation help, refer to eBay API documentation"
- },
- "startDate": {
- "type": "string",
- "description": "The date and time the promotion starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
- }
- },
- "description": "This complex type defines the fields returned for an item (threshold) promotion."
- },
- "ItemsPagedCollection": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the current page of results from the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
- "format": "int32"
- },
- "listings": {
- "type": "array",
- "description": "An array of the listings associated with a promotion.",
- "items": {
- "$ref": "#/components/schemas/ListingDetail"
- }
- },
- "next": {
- "type": "string",
- "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
- },
- "total": {
- "type": "integer",
- "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
- "format": "int32"
- },
- "warnings": {
- "type": "array",
- "description": "A list of warnings that were generated by the request. Warning do not stop processing, but should be checked to ensure that the response contains the correct information.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- },
- "description": "This type defines the fields for a paginated result set of promotions. The response consists of 0 or more sequenced pages that are returned from the complete result set, where each page consists of 0 or more items."
- },
- "Keyword": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "This field identifies the ad group that the keyword is associated with."
- },
- "bid": {
- "description": "The bid associated with the keyword. This container will not be returned if the keyword does not have a defined bid value.",
- "$ref": "#/components/schemas/Amount"
- },
- "keywordId": {
- "type": "string",
- "description": "The unique identifier of a keyword."
- },
- "keywordStatus": {
- "type": "string",
- "description": "The status of the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
- },
- "keywordText": {
- "type": "string",
- "description": "The text of the keyword."
- },
- "matchType": {
- "type": "string",
- "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A type that contains the details for keywords that are associated with an ad group.
Note: This type only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model."
- },
- "KeywordPagedCollectionResponse": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the current page of results from the result set."
- },
- "keywords": {
- "type": "array",
- "description": "This array contains all of the keywords that match the request criteria. Keywords will be sorted by adGroupId, regardless of whether you searched for keywords across the entire campaign, or if you searched for keywords within one or specific ad groups.",
- "items": {
- "$ref": "#/components/schemas/Keyword"
- }
- },
- "limit": {
- "type": "integer",
- "description": "The number of keywords returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results.
Max length: 2048"
- },
- "total": {
- "type": "integer",
- "description": "The total number of keywords retrieved in the result set.
If no keywords are found, this field is returned with a value of 0.",
- "format": "int32"
- }
- },
- "description": "A type that defines the keywords of the paged collection."
- },
- "KeywordRequest": {
- "type": "object",
- "properties": {
- "keywordText": {
- "type": "string",
- "description": "The text of the keyword. Keywords are not case sensitive and compound words can be used without additional encoding (for example, tennis ball).
Maximum number of characters: 100
Maximum number of words: 10 "
- },
- "matchType": {
- "type": "string",
- "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A type that defines the fields used by the Keyword method."
- },
- "KeywordResponse": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "The identifier of the ad group that the keyword was added to."
- },
- "errors": {
- "type": "array",
- "description": "This container will be returned if there is an issue creating the corresponding keyword and/or adding that keyword to the corresponding ad group.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "href": {
- "type": "string",
- "description": "The getKeyword URI for the keyword, which is used to retrieve the keyword. This URI will be returned for each successfully created keyword."
- },
- "keywordId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a keyword that is generated for an ad group. This keyword ID will be generated for each successfully created keyword."
- },
- "keywordText": {
- "type": "string",
- "description": "The text of the keyword."
- },
- "matchType": {
- "type": "string",
- "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
- },
- "statusCode": {
- "type": "integer",
- "description": "An HTTP status code is returned for each keyword to indicate the success or failure of adding that keyword to the ad group.",
- "format": "int32"
- }
- },
- "description": "A type that defines the response fields used by the Keyword method."
- },
- "ListingDetail": {
- "type": "object",
- "properties": {
- "currentPrice": {
- "description": "The container that returns the current price of the listing.",
- "$ref": "#/components/schemas/Amount"
- },
- "freeShipping": {
- "type": "boolean",
- "description": "If set to true, the seller pays for the shipping (or that the item is marked for local pickup only) In this case, the listing does not have an associated shipping cost for the first listed domestic-shipping option (even if the first domestic-shipping option specifies a flat-rate or calculated shipping option). If false, the buyer is required to pay for a flat-rate or calculated cost shipping service."
- },
- "inventoryReferenceId": {
- "type": "string",
- "description": "The seller's inventory reference ID for a listing. Also known as the \"SKU\" or \"custom label,\" an inventory reference ID is either the ID of the listing or, if the listing has variations (such as a shirt that's available in multiple sizes and colors), the ID of the parent listing."
- },
- "inventoryReferenceType": {
- "type": "string",
- "description": "Indicates the type of the inventoryReferenceId, which can be either a single-SKU or a multi-SKU listing (INVENTORY_ITEM and INVENTORY_ITEM_GROUP, respectively).
Note: This value is not currently returned in the response."
- },
- "listingCategoryId": {
- "type": "string",
- "description": "The ID of the category that listing belongs to. The ID is a numeric and unique identifier for the category that is assigned by eBay."
- },
- "listingCondition": {
- "type": "string",
- "description": "An eBay-assigned value that indicates condition of the associated item. For more information, see Item condition ID and name values."
- },
- "listingConditionId": {
- "type": "string",
- "description": "The ID of the condition associated with the item. For more information, see Item condition ID and name values.
Note: This value is not currently returned in the response."
- },
- "listingId": {
- "type": "string",
- "description": "A unique eBay-assigned ID that is generated when the item is listed."
- },
- "listingPromotionStatuses": {
- "type": "array",
- "description": "A list of the status values assigned to the item and the date that each new status was assigned.",
- "items": {
- "$ref": "#/components/schemas/ItemMarkdownStatus"
- }
- },
- "quantity": {
- "type": "integer",
- "description": "The number of items being sold in the listing.",
- "format": "int32"
- },
- "storeCategoryId": {
- "type": "string",
- "description": "Store CategoryId (if any) that to which the listing belongs. This field is blank if there is no seller Store category ID."
- },
- "title": {
- "type": "string",
- "description": "The seller-defined title of the listing that a seller can use to identify the item. This label is not displayed in end-user flows."
- }
- },
- "description": "This type defines the fields that describe a listing that is in a promotion."
- },
- "MetricMetadata": {
- "type": "object",
- "properties": {
- "dataType": {
- "type": "string",
- "description": "The data type of the returned metric value. For implementation help, refer to eBay API documentation"
- },
- "metricKey": {
- "type": "string",
- "description": "The name of the metric."
- }
- },
- "description": "This type defines the name and data type of a metric."
- },
- "NegativeKeyword": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "An ad group ID that is generated when an ad group is first created and associated with a campaign.
Note: You can call the getAdGroups method to retrieve the ad group IDs for a seller."
- },
- "campaignId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created."
- },
- "negativeKeywordId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a negative keyword. This keyword ID will be generated for each successfully created negative keyword."
- },
- "negativeKeywordMatchType": {
- "type": "string",
- "description": "A field that defines the match type for the negative keyword.
Note: Broad matching of negative keywords is not currently supported.
Valid Values: For implementation help, refer to eBay API documentation"
- },
- "negativeKeywordStatus": {
- "type": "string",
- "description": "A field that defines the status of the negative keyword. For implementation help, refer to eBay API documentation"
- },
- "negativeKeywordText": {
- "type": "string",
- "description": "The text for the negative keyword."
- }
- },
- "description": "A type that defines the fields for a negative keyword."
- },
- "NegativeKeywordPagedCollectionResponse": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the current page of results from the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
- "format": "int32"
- },
- "negativeKeywords": {
- "type": "array",
- "description": "A list of negative keywords returned in the paginated collection.",
- "items": {
- "$ref": "#/components/schemas/NegativeKeyword"
- }
- },
- "next": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set."
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.
Default: 0
Note: The items in a paginated result set use a zero-based list, where the first item in the list has an offset of 0.",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results."
- },
- "total": {
- "type": "integer",
- "description": "The total number of result sets in the paginated collection.",
- "format": "int32"
- }
- },
- "description": "A type that defines the negative keywords, returned in a paged collection."
- },
- "NegativeKeywordResponse": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "A unique identifier for an ad group that is generated when an ad group is first created and associated with a campaign."
- },
- "campaignId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created."
- },
- "errors": {
- "type": "array",
- "description": "This container will be returned if there is an issue creating the corresponding negative keyword.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "href": {
- "type": "string",
- "description": "The URI for the negative keyword, which is used to retrieve the negative keyword. This URI will be returned for each successfully created negative keyword."
- },
- "negativeKeywordId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a negative keyword. This negative keyword ID will be generated for each successfully created negative keyword."
- },
- "negativeKeywordMatchType": {
- "type": "string",
- "description": "The match type for the negative keyword.
Note: Broad matching of negative keywords is not currently supported.
Valid Values: For implementation help, refer to eBay API documentation"
- },
- "negativeKeywordText": {
- "type": "string",
- "description": "The text for the negative keyword."
- },
- "statusCode": {
- "type": "integer",
- "description": "The status of the request to create a negative keyword. This field indicates whether the process was successful or not.",
- "format": "int32"
- }
- },
- "description": "A type that defines the negative keyword response."
- },
- "PriceRange": {
- "type": "object",
- "properties": {
- "currency": {
- "type": "string",
- "description": "Specifies the currency of the listings in an email campaign using one of the three-digit codes of the CurrencyCodeEnum type."
- },
- "gte": {
- "type": "number",
- "description": "The listings selected will be greater than or equal to this value. The value entered must be given in number format, such as 20.00.
Either gte, lte, or both must contain a value if the seller wishes to use a price range."
- },
- "lte": {
- "type": "number",
- "description": "The listings selected will be less than or equal to this value. The value entered must be given in number format, such as 100.00.
Either gte, lte, or both must contain a value if the seller wishes to use a price range."
- }
- },
- "description": "The price range."
- },
- "PromotionDetail": {
- "type": "object",
- "properties": {
- "couponCode": {
- "type": "string",
- "description": "A unique code that buyers can use during checkout to receive a discount. The code must be unique across eBay."
- },
- "description": {
- "type": "string",
- "description": "This is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\" Tag lines appear under the \"offer-type text\" that is generated for a promotion and displayed under the offer tile that is shown on the seller's All Offers page and on the promotion's event page. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. This text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"Extra 20% off when you buy 3+\".
Maximum length: 50
Required if you are configuring ORDER_DISCOUNT or MARKDOWN_SALE promotions (and not valid for VOLUME_DISCOUNT promotions)."
- },
- "endDate": {
- "type": "string",
- "description": "The date and time the promotion ends in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
- },
- "marketplaceId": {
- "type": "string",
- "description": "The eBay marketplace ID of the site where the promotion is hosted. Threshold promotions are supported on a select set of marketplaces while markdown promotions are supported on all eBay marketplaces. Valid values for threshold promotions are as follows:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
For implementation help, refer to eBay API documentation"
- },
- "name": {
- "type": "string",
- "description": "The seller-defined name or \"title\" of the promotion, such as \"Buy 1 Get 1\", that the seller can use to identify a promotion. This label is not displayed in end-user flows.
Maximum length: 90"
- },
- "priority": {
- "type": "string",
- "description": "Applicable for only ORDER_DISCOUNT promotions, this field indicates the precedence of the promotion, which is used to determine the position of a promotion on the seller's All Offers page. If an item is associated with multiple promotions, the promotion with the higher priority takes precedence. For implementation help, refer to eBay API documentation"
- },
- "promotionHref": {
- "type": "string",
- "description": "The URI of the promotion details."
- },
- "promotionId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for the promotion that's generated when the promotion is created."
- },
- "promotionImageUrl": {
- "type": "string",
- "description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT promotions, and not applicable for VOLUME_DISCOUNT promotions, this field is a URL that points to an image for the promotion. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
- },
- "promotionStatus": {
- "type": "string",
- "description": "The current status of the promotion. When creating a new promotion, you must set this value to either DRAFT or SCHEDULED. For implementation help, refer to eBay API documentation"
- },
- "promotionType": {
- "type": "string",
- "description": "Indicates type of the promotion, either CODED_COUPON, MARKDOWN_SALE, ORDER_DISCOUNT, or VOLUME_DISCOUNT. For implementation help, refer to eBay API documentation"
- },
- "startDate": {
- "type": "string",
- "description": "The date and time the promotion starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
- }
- },
- "description": "This type defines the fields that describe a promotion. This includes all the information about a promotion except for the listings that are a part of the promotion."
- },
- "PromotionReportDetail": {
- "type": "object",
- "properties": {
- "averageItemDiscount": {
- "description": "The average item discount is the average discount that has been applied to each item in a promotion. This value is calculated as follows:
totalDiscount / itemsSoldQuantity = averageItemDiscount",
- "$ref": "#/components/schemas/Amount"
- },
- "averageItemRevenue": {
- "description": "The average item revenue is the average revenue that has been received for each item in a promotion. This value is calculated as follows:
totalSales / itemsSoldQuantity = averageItemRevenue",
- "$ref": "#/components/schemas/Amount"
- },
- "averageOrderDiscount": {
- "description": "The average order discount is the average discount that has been applied to each order in a promotion. This value is calculated as follows:
totalDiscount / numberOfOrdersSold = averageOrderDiscount",
- "$ref": "#/components/schemas/Amount"
- },
- "averageOrderRevenue": {
- "description": "The average order revenue is the average revenue that has been received for each order in a promotion. This value is calculated as follows:
totalSales / numberOfOrdersSold = averageOrderRevenue",
- "$ref": "#/components/schemas/Amount"
- },
- "averageOrderSize": {
- "type": "string",
- "description": "The average order size is the average number of items that each order contained in a promotion. This value is calculated as follows:
itemsSoldQuantity / numberOfOrdersSold = averageOrderSize "
- },
- "baseSale": {
- "description": "This is the monetary amount of items purchased in a promotion where the threshold wasn't met, so the discount was not applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" promotion on $5 socks. One buyer purchased only one pair of socks, so they pay the full price of $5. Here, your baseSale amount would be $5.",
- "$ref": "#/components/schemas/Amount"
- },
- "itemsSoldQuantity": {
- "type": "integer",
- "description": "This is the quantity of items purchased in a threshold promotion where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" promotion on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your number of items sold (itemsSoldQuantity) would be 2 and you number of orders sold (numberOfOrdersSold) would be 1.",
- "format": "int32"
- },
- "numberOfOrdersSold": {
- "type": "integer",
- "description": "This is the number of orders sold in a threshold promotion where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" promotion on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your numberOfOrdersSold would be 1 and your itemsSoldQuantity would be 2.",
- "format": "int32"
- },
- "percentageSalesLift": {
- "type": "string",
- "description": "The percentage sales lift is the total dollar amount gained due to promotions. This value is calculated as follows:
promotionSale / totalSale = percentageSalesLift "
- },
- "promotionHref": {
- "type": "string",
- "description": "The URI of the promotion report."
- },
- "promotionId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for the promotion that's generated when the promotion is created."
- },
- "promotionReportId": {
- "type": "string",
- "description": "The unique eBay-assigned ID of the promotion report that is generated when the report is created."
- },
- "promotionSale": {
- "description": "This is the monetary amount of the items sold in a threshold promotion where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" promotion on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your promotionSale amount would be $7.50.",
- "$ref": "#/components/schemas/Amount"
- },
- "promotionType": {
- "type": "string",
- "description": "Indicates the type of the promotion, either CODED_COUPON, MARKDOWN_SALE, ORDER_DISCOUNT, or VOLUME_DISCOUNT. For implementation help, refer to eBay API documentation"
- },
- "totalDiscount": {
- "description": "This is the monetary discount amount applied to the sale of items in a threshold promotion where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" promotion on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your totalDiscount amount would be $2.50.",
- "$ref": "#/components/schemas/Amount"
- },
- "totalSale": {
- "description": "This is the total monetary sales amount of all items sold in a promotion.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" promotion on $5 socks. You make one sale where the buyer purchases only one pair of socks and they pay the full price of $5 (baseSale). You make a second sale where the buyer purchases two pairs of socks and they pay $7.50, for both pairs (promotionSale). Your totalSale would be $12.50. This value is calculated as follows:
baseSale + promotionSale = totalSale",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type defines the fields in a promotion-level report."
- },
- "PromotionsPagedCollection": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the current page of results from the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
- },
- "promotions": {
- "type": "array",
- "description": "A list containing the details of each returned promotion. This includes all the information about the promotions except for the listings that are part of the promotions.",
- "items": {
- "$ref": "#/components/schemas/PromotionDetail"
- }
- },
- "total": {
- "type": "integer",
- "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
- "format": "int32"
- }
- },
- "description": "This type defines the fields in a paginated result set of seller promotions. The response consists of 0 or more sequenced pages that are returned from the complete result set, where each page consists of 0 or more items."
- },
- "PromotionsReportPagedCollection": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the current page of results from the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
- },
- "promotionReports": {
- "type": "array",
- "description": "A list of promotionReports contained in the paginated result set.",
- "items": {
- "$ref": "#/components/schemas/PromotionReportDetail"
- }
- },
- "total": {
- "type": "integer",
- "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
- "format": "int32"
- }
- },
- "description": "This type defines the fields in a paginated result set of promotion-level reports. The response consists of 0 or more sequenced pages that are returned from the complete result set, where each page consists of 0 or more items."
- },
- "ProposedBid": {
- "type": "object",
- "properties": {
- "currency": {
- "type": "string",
- "description": "The base currency applied to the value field to establish a monetary amount.
The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.
Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation"
- },
- "rangeEnd": {
- "type": "string",
- "description": "The end of the range specified for the bid."
- },
- "rangeStart": {
- "type": "string",
- "description": "The start of the range specified for the bid."
- },
- "value": {
- "type": "string",
- "description": "The value of the proposed bid."
- }
- },
- "description": "A type that defines the data for a payment amount, such as the sale price."
- },
- "QuickSetupRequest": {
- "type": "object",
- "properties": {
- "budget": {
- "description": "The allocated daily budget for a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model.",
- "$ref": "#/components/schemas/CampaignBudgetRequest"
- },
- "campaignName": {
- "type": "string",
- "description": "The seller-defined name for the campaign. This value must be unique for the seller.
You can use any alphanumeric characters in the name, except for the less than (<) and greater than (>) characters.
Max Length: 80 characters"
- },
- "endDate": {
- "type": "string",
- "description": "The date and time the campaign is scheduled to end, in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).
If this field is omitted, the campaign will have no defined end date, and will not end until the seller ends the campaign using the endCampaign method, or if they update the campaign to include an end date using the updateCampaignIdentification method. This date must be further in the future than the startDate. "
- },
- "listingIds": {
- "type": "array",
- "description": "This array includes the listing Ids of the items that are to be associated with the PLA campaign. eBay will create ad groups and keywords for these listings and add them to the campaign.
Each value must be delimited by a comma. A maximum of 1000 listing Ids can be added to a campaign created using the setupQuickCampaign method. ",
- "items": {
- "type": "string"
- }
- },
- "marketplaceId": {
- "type": "string",
- "description": "The Id of the marketplace where the campaign is hosted. See the MarkeplaceIdEnum type for more details. For implementation help, refer to eBay API documentation"
- },
- "startDate": {
- "type": "string",
- "description": "The date and time the campaign is scheduled to start, in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).
On the specified date, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts once this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign.
Note: If the startDate has passed by the time the seller launches a campaign, the campaign will be updated to RUNNING status. If the seller launches a campaign before the startDate, the campaign will be updated to SCHEDULED status and will change to RUNNING status at the time of the specified startDate."
- }
- },
- "description": "This type defines the fields needed to create a quick setup PLA campaign. To create a quick setup campaign, a seller must specify the name, start date, and marketplace of the campaign. The seller must also specify the listing Ids of the items they want associated with the campaign."
- },
- "ReportMetadata": {
- "type": "object",
- "properties": {
- "dimensionMetadata": {
- "type": "array",
- "description": "A list containing the metadata for the dimension used in the report.",
- "items": {
- "$ref": "#/components/schemas/DimensionMetadata"
- }
- },
- "maxNumberOfDimensionsToRequest": {
- "type": "integer",
- "description": "The maximum number of dimensions that can be requested for the specified report type.",
- "format": "int32"
- },
- "maxNumberOfMetricsToRequest": {
- "type": "integer",
- "description": "The maximum number of metrics that can be requested for the specified report type.",
- "format": "int32"
- },
- "metricMetadata": {
- "type": "array",
- "description": "A list containing the metadata for the metrics in the report.",
- "items": {
- "$ref": "#/components/schemas/MetricMetadata"
- }
- },
- "reportType": {
- "type": "string",
- "description": "The report_type, as specified in the request to create the report task.
Note: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type defines the fields included in the report."
- },
- "ReportMetadatas": {
- "type": "object",
- "properties": {
- "reportMetadata": {
- "type": "array",
- "description": "A list of the metadata for the associated report type.",
- "items": {
- "$ref": "#/components/schemas/ReportMetadata"
- }
- }
- },
- "description": "This type defines the metadata used by the all report types."
- },
- "ReportTask": {
- "type": "object",
- "properties": {
- "campaignIds": {
- "type": "array",
- "description": "A list of IDs for the campaigns that are included in the report. A campaign ID is a unique eBay-assigned identifier of the campaign that's generated when the campaign is created.
Call getCampaigns to return the current campaign IDs for a seller.",
- "items": {
- "type": "string"
- }
- },
- "dateFrom": {
- "type": "string",
- "description": "The date defining the start of the timespan covered by the report, formatted as an ISO 8601 timestamp."
- },
- "dateTo": {
- "type": "string",
- "description": "The date defining the end of the timespan covered by the report, formatted as an ISO 8601 timestamp."
- },
- "dimensions": {
- "type": "array",
- "description": "A list containing the dimension in the report.",
- "items": {
- "$ref": "#/components/schemas/Dimension"
- }
- },
- "fundingModels": {
- "type": "array",
- "description": "The funding model for the campaign that shall be included in the report.
Note: The default funding model for Promoted Listings reports is COST_PER_SALE.
Valid Values:COST_PER_SALECOST_PER_CLICK
",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- },
- "inventoryReferences": {
- "type": "array",
- "description": "If supplied in the request, this field returns a list of the seller's inventory reference IDs included in the report. Each item is referenced by a pair of inventoryRefernceID and inventoryReferenceType values, where an inventory reference ID can be either a seller-defined SKU value or an inventoryItemGroupKey. An inventoryItemGroupKey is seller-defined ID for an inventory item group (a multiple-variation listing), and is created and used by the Inventory API.
",
- "items": {
- "$ref": "#/components/schemas/InventoryReference"
- }
- },
- "listingIds": {
- "type": "array",
- "description": "If supplied in the request, this field returns a list of the listing IDs included in the report. A listing ID is an eBay-assigned ID that's generated when a listing is created.",
- "items": {
- "type": "string"
- }
- },
- "marketplaceId": {
- "type": "string",
- "description": "The ID of the eBay marketplace used by the report task. For implementation help, refer to eBay API documentation"
- },
- "metricKeys": {
- "type": "array",
- "description": "A list of metrics for the report task.",
- "items": {
- "type": "string"
- }
- },
- "reportExpirationDate": {
- "type": "string",
- "description": "The date after which the report is no longer be available. Reports are available for 30 days and you cannot download a report after it has expired.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
- },
- "reportFormat": {
- "type": "string",
- "description": "Indicates the format of the report. Currently, only TSV_GZIP is supported. For implementation help, refer to eBay API documentation"
- },
- "reportHref": {
- "type": "string",
- "description": "The URL of the generated report, which can be used to download the report once it has been generated."
- },
- "reportId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for the report."
- },
- "reportName": {
- "type": "string",
- "description": "An eBay-assigned name for the report that's created by the createReportTask call. This name is unique for the seller."
- },
- "reportTaskCompletionDate": {
- "type": "string",
- "description": "The date the report task completed the report generation.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
- },
- "reportTaskCreationDate": {
- "type": "string",
- "description": "The date the report task was created.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
- },
- "reportTaskExpectedCompletionDate": {
- "type": "string",
- "description": "The date the report task is expected to complete the report generation.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
- },
- "reportTaskId": {
- "type": "string",
- "description": "The unique eBay-assigned ID of the report task. This value is generated when the report task is created with a call to createReportTask."
- },
- "reportTaskStatus": {
- "type": "string",
- "description": "Indicates the current state of the report task. For implementation help, refer to eBay API documentation"
- },
- "reportTaskStatusMessage": {
- "type": "string",
- "description": "A status message with additional information about the report task."
- },
- "reportType": {
- "type": "string",
- "description": "Indicates type of report associated with the report task.
Note: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "This type defines the fields in a report task."
- },
- "ReportTaskPagedCollection": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the current page of results from the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.
Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
- },
- "total": {
- "type": "integer",
- "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
- "format": "int32"
- },
- "reportTasks": {
- "type": "array",
- "description": "A list of report tasks contained on this page from the paginated response.",
- "items": {
- "$ref": "#/components/schemas/ReportTask"
- }
- }
- },
- "description": "This type defines the fields that paginate the reports tasks returned by the request. The entire result set consists of 0 or more sequenced response pages, where each page consists of 0 or more items from the complete result set."
- },
- "RuleCriteria": {
- "type": "object",
- "properties": {
- "excludeInventoryItems": {
- "type": "array",
- "description": "A list of seller inventory reference IDs to exclude from the promotion.
Note: The request can have either excludeInventoryItems or excludeListingIds but not both.
Maximum: 100 parent items
Maximum SKU or custom label length: 50 characters",
- "items": {
- "$ref": "#/components/schemas/InventoryItem"
- }
- },
- "excludeListingIds": {
- "type": "array",
- "description": "A list of eBay listing IDs to exclude from the promotion.
Note: The request can have either excludeInventoryItems or excludeListingIds but not both.
Maximum: 100 parent items
Maximum SKU or custom label length: 50 characters",
- "items": {
- "type": "string"
- }
- },
- "markupInventoryItems": {
- "type": "array",
- "description": "A list of SKUs to remove from a markdown promotion. The listed SKUs are 'marked up' to their standard price after being part of the markdown promotion.",
- "items": {
- "$ref": "#/components/schemas/InventoryItem"
- }
- },
- "markupListingIds": {
- "type": "array",
- "description": "A list of listing IDs to remove from a markdown promotion. The listed items are 'marked up' to their standard price after being part of the markdown promotion.",
- "items": {
- "type": "string"
- }
- },
- "selectionRules": {
- "type": "array",
- "description": "The container for the rules that select the items to include in a promotion.
Required if inventoryCriterionType is set to INVENTORY_BY_RULE.
For information on using the contained fields, see Item promotions.",
- "items": {
- "$ref": "#/components/schemas/SelectionRule"
- }
- }
- },
- "description": "This type defines the fields for a set of inventory selection rules.
Required: When inventoryCriterionType is set to INVENTORY_BY_RULE or INVENTORY_ANY."
- },
- "SelectedInventoryDiscount": {
- "type": "object",
- "properties": {
- "discountBenefit": {
- "description": "This container defines the promotional discount as either a monetary amount or a percentage applied to the sales price.",
- "$ref": "#/components/schemas/DiscountBenefit"
- },
- "discountId": {
- "type": "string",
- "description": "A unique, eBay-generated ID that you can use to identify the discount. This field is ignored in POST and PUT operations."
- },
- "inventoryCriterion": {
- "description": "A container that defines either the listing IDs or the selection rules that specify the items to include in the promotion. Listing IDs can be either eBay listing IDs or a list of the seller's inventory reference IDs (know as SKUs or custom labels). See the selectionRules container for the rule criteria you can use to select inventory. Note: All listings in Promotions Manager promotions must support an electronic payment method.
",
- "$ref": "#/components/schemas/InventoryCriterion"
- },
- "ruleOrder": {
- "type": "integer",
- "description": "For markdown promotions, this field is reserved for future use. ",
- "format": "int32"
- }
- },
- "description": "This type defines the fields that describe the discounts applied to a set of inventory items and the order in which the selection rules are applied."
- },
- "SelectionRule": {
- "type": "object",
- "properties": {
- "brands": {
- "type": "array",
- "description": "An array of product brands. For more details, see Using the selectionRules container.",
- "items": {
- "type": "string"
- }
- },
- "categoryIds": {
- "type": "array",
- "description": "This field contains an array of the associated category ID(s).
For Item promotions, a single-item array containing the category ID associated with the promotion. Required when used in an Item promotion and either specifying a selectionRules container or when inventoryCriterionType is set to INVENTORY_BY_RULE.
For Promoted Listing campaigns, an array of category ID(s) associated with the campaign.
For information on how to get category IDs, see eBay Marketplace category IDs and Seller store category IDs",
- "items": {
- "type": "string"
- }
- },
- "categoryScope": {
- "type": "string",
- "description": "This enumerated value indicates if the category ID for the item is an identifier for eBay categories or for a seller's eBay store categories.
For Promoted Listing campaigns, this field includes the type of the category ID for the item(s) to be included in the campaign.
For Item promotions, this field identifies the scope for the corresponding array as eBay categories or for a seller's eBay store categories. Required when used in an Item promotion and inventoryCriterionType is set to INVENTORY_BY_RULE. For implementation help, refer to eBay API documentation"
- },
- "listingConditionIds": {
- "type": "array",
- "description": "A comma-separated list of unique identifiers for the conditions of listings to be included
For Promoted Listing campaigns, refer to Add items to the PLS campaign. Up to four IDs can be specified.
For Item promotions, refer to Item condition ID and name values.",
- "items": {
- "type": "string"
- }
- },
- "maxPrice": {
- "description": "This container sets the maximum price threshold. For more details, see Using the selectionRules container.",
- "$ref": "#/components/schemas/Amount"
- },
- "minPrice": {
- "description": "This container sets the minimum price threshold. For more details, see Using the selectionRules container.",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type defines all rules/inclusion filters used to add listings to campaigns or promotions. Use of the specific fields is different for campaigns or promotions. See Using the selectionRules container."
- },
- "SuggestedBids": {
- "type": "object",
- "properties": {
- "keywordText": {
- "type": "string",
- "description": "The text for the keyword."
- },
- "matchType": {
- "type": "string",
- "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
- },
- "proposedBid": {
- "description": "The suggested bid associated with the keyword. ",
- "$ref": "#/components/schemas/ProposedBid"
- }
- },
- "description": "The suggested bid rate for the item."
- },
- "SuggestedKeywords": {
- "type": "object",
- "properties": {
- "additionalInfo": {
- "type": "array",
- "description": "A container for the additional information and compiled insight data for suggested keywords. ",
- "items": {
- "$ref": "#/components/schemas/AdditionalInfo"
- }
- },
- "keywordText": {
- "type": "string",
- "description": "The text for the keyword."
- },
- "matchType": {
- "type": "string",
- "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
- }
- },
- "description": "The suggested keywords for the item."
- },
- "SummaryReportResponse": {
- "type": "object",
- "properties": {
- "baseSale": {
- "description": "The total revenue from all the purchased items that were part of a promotion but did not trigger a discount during the promotion period.",
- "$ref": "#/components/schemas/Amount"
- },
- "lastUpdated": {
- "type": "string",
- "description": "The date the report was generated."
- },
- "percentageSalesLift": {
- "type": "string",
- "description": "The percentage of the total dollar amount gained due to promotions. This value is calculated as follows:
precentageSalesLift = promotionSale / (baseSale + promotionSale)"
- },
- "promotionSale": {
- "description": "The total revenue from all the purchased items that were part of a promotion and their purchase did trigger a discount during the promotion period.",
- "$ref": "#/components/schemas/Amount"
- },
- "totalSale": {
- "description": "Total dollar sales amount of all the seller's listings, current to the date the report was generated.",
- "$ref": "#/components/schemas/Amount"
- }
- },
- "description": "This type defines the fields in an Promotions Manager Summary report. Reports are formatted in JSON. For more details, see Reading item promotion Summary reports."
- },
- "TargetedAdsPagedCollection": {
- "type": "object",
- "properties": {
- "href": {
- "type": "string",
- "description": "The URI of the current page of results from the result set."
- },
- "limit": {
- "type": "integer",
- "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
- "format": "int32"
- },
- "next": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set."
- },
- "offset": {
- "type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Default: 0
Note: The items in a paginated result set use a zero-based list, where the first item in the list has an offset of 0.",
- "format": "int32"
- },
- "prev": {
- "type": "string",
- "description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results."
- },
- "suggestedItems": {
- "type": "array",
- "description": "A list of suggested items in the paginated collection.",
- "items": {
- "$ref": "#/components/schemas/TargetingItems"
- }
- },
- "total": {
- "type": "integer",
- "description": "The total number of items retrieved in the result set.
Note: If no items are found, this field is returned with a value of 0.",
- "format": "int32"
- }
- },
- "description": "A type that defines the keywords of the paged collection."
- },
- "TargetedBidRequest": {
- "type": "object",
- "properties": {
- "keywords": {
- "type": "array",
- "description": "A list of keywords in the paginated collection.
Maximum number of keywords: 500",
- "items": {
- "$ref": "#/components/schemas/KeywordRequest"
- }
- }
- },
- "description": "A type that defines the targeted bid."
- },
- "TargetedBidsPagedCollection": {
- "type": "object",
- "properties": {
- "suggestedBids": {
- "type": "array",
- "description": "A list of bids in the paginated collection.",
- "items": {
- "$ref": "#/components/schemas/SuggestedBids"
- }
- }
- },
- "description": "A type that defines the keywords of the paged collection."
- },
- "TargetedKeywordRequest": {
- "type": "object",
- "properties": {
- "additionalInfo": {
- "type": "array",
- "description": "A field used to indicate whether additional information and insight data shall be provided for suggested keywords.
Valid Value: KEYWORD_INSIGHTS",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- },
- "exclusions": {
- "type": "array",
- "description": "A field used to indicate that the keywords already selected by sellers for the specified listing IDs should be filtered out of the response, and only new and unique keyword recommendations shall be returned.
Valid Value: ADOPTED_KEYWORDS",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- },
- "listingIds": {
- "type": "array",
- "description": "A set of comma-separated listing IDs in the paginated collection.
Maximum number of listings requested: 300",
- "items": {
- "type": "string"
- }
- },
- "matchType": {
- "type": "string",
- "description": "A field that defines the match type for the keyword.
Valid Values: For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A type that provides details for the targeted keywords."
- },
- "TargetedKeywordsPagedCollection": {
- "type": "object",
- "properties": {
- "suggestedKeywords": {
- "type": "array",
- "description": "A list of suggested keywords in the paged collection. Note: A relevancy check with items already present in the ad-group is performed even if item IDs associated with the ad-group are not explicitly passed in the request.
",
- "items": {
- "$ref": "#/components/schemas/SuggestedKeywords"
- }
- }
- },
- "description": "A type that defines the keywords of the paged collection."
- },
- "TargetingItems": {
- "type": "object",
- "properties": {
- "bases": {
- "type": "array",
- "description": "The metrics and additional information for the items.",
- "items": {
- "$ref": "#/components/schemas/ItemBasis"
- }
- },
- "listingId": {
- "type": "string",
- "description": "The listing ID of the targeted item."
- }
- },
- "description": "A type that defines the targeted items."
- },
- "UpdateAdGroupRequest": {
- "type": "object",
- "properties": {
- "adGroupStatus": {
- "type": "string",
- "description": "An enumeration value representing the current status of the ad group.If the status of the ad is currently ACTIVE, you can change status to PAUSED or ARCHIVED. If ad group is currently in PAUSED status, you can change the status back to ACTIVE. Ads that are currently in ARCHIVED status cannot be made ACTIVE again.
Valid Values:
For implementation help, refer to eBay API documentation"
- },
- "defaultBid": {
- "description": "A bid amount that applies to all of the keywords in an ad group that do not have individual bids.",
- "$ref": "#/components/schemas/Amount"
- },
- "name": {
- "type": "string",
- "description": "The updated name for the specified ad group."
- }
- },
- "description": "A type that contains the fields used by the UpdateAdGroup request."
- },
- "UpdateAdStatusByListingIdRequest": {
- "type": "object",
- "properties": {
- "adGroupId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model.
Note: You can call the getAdGroups method to retrieve the ad group IDs for a seller."
- },
- "adStatus": {
- "type": "string",
- "description": "An enumeration value representing the current status of the ad.
Valid Values: For implementation help, refer to eBay API documentation"
- },
- "listingId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a listing that is generated when the listing is created.
Note: This field accepts both listing IDs (as generated by the Inventory API), and item IDs (as used in the eBay Traditional API set, such as the Trading and Finding APIs)."
- }
- },
- "description": "A type that contains the fields for the UpdateAdStatusByListingId request."
- },
- "UpdateAdStatusRequest": {
- "type": "object",
- "properties": {
- "adId": {
- "type": "string",
- "description": "A unique eBay-assigned ID that is generated when the ad is created."
- },
- "adStatus": {
- "type": "string",
- "description": "An enumeration value representing the current status of the ad.
Valid Values: For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A type that contains the fields for the UpdateAdStatus request."
- },
- "UpdateAdrateStrategyRequest": {
- "type": "object",
- "properties": {
- "adRateStrategy": {
- "type": "string",
- "description": "The ad rate strategy that shall be applied to the campaign. For implementation help, refer to eBay API documentation"
- },
- "bidPercentage": {
- "type": "string",
- "description": "The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
This is the default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.
Minimum value: 2.0
Maximum value: 100.0"
- },
- "dynamicAdRatePreferences": {
- "type": "array",
- "description": "A field that indicates whether a single, user-defined bid percentage (also known as the ad rate) should be used, or whether eBay should automatically adjust listings to maintain the daily suggested bid percentage.
Note: Dynamic adjustment is only applicable when the adRateStrategy is set to DYNAMIC.
Default: FIXED",
- "items": {
- "$ref": "#/components/schemas/DynamicAdRatePreference"
- }
- }
- },
- "description": "A type that defines the request fields used to update the ad rate strategy for a Promoted Listings ad campaign."
- },
- "UpdateAdsByInventoryReferenceResponse": {
- "type": "object",
- "properties": {
- "ads": {
- "type": "array",
- "description": "A list of ad IDs and links to retrieve them.",
- "items": {
- "$ref": "#/components/schemas/AdReference"
- }
- },
- "errors": {
- "type": "array",
- "description": "A container for all of the errors associated with the specified inventory reference ID.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "inventoryReferenceId": {
- "type": "string",
- "description": "The reference ID associated with the ad. The reference ID could be a SKU number or Inventory Item Group, depending on value of inventoryReferenceType."
- },
- "inventoryReferenceType": {
- "type": "string",
- "description": "The inventory reference type associated with the ad. The inventory reference type could be a SKU number or Inventory Item Group. For implementation help, refer to eBay API documentation"
- },
- "statusCode": {
- "type": "integer",
- "description": "An HTTP status code that indicates whether or not the CPS ad was successfully updated.",
- "format": "int32"
- }
- },
- "description": "A type that contains the response fields used by the UpdateAdsByInventoryReference method."
- },
- "UpdateBidPercentageRequest": {
- "type": "object",
- "properties": {
- "bidPercentage": {
- "type": "string",
- "description": "The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.
The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.
The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.
The bidPercentage is a single precision value that is guided by the following rules: - These values are valid:
4.1, 5.0, 5.5, ... - These values are not valid:
0.01, 10.75, 99.99,
and so on.
This is default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.
Minimum value: 2.0
Maximum value: 100.0"
- }
- },
- "description": "This type specifies the bid percentage for an ad campaign."
- },
- "UpdateCampaignBudgetRequest": {
- "type": "object",
- "properties": {
- "daily": {
- "description": "The daily budget limit for the Cost Per Click (CPC) Promoted Listings campaign. This will be a dollar value. All clicks using the keywords defined for the campaign will go towards expending the daily budget. Once the daily budget is exceeded for the campaign, all Promoted Listings under the campaign will be turned off until the next day.
Valid Values:",
- "$ref": "#/components/schemas/BudgetRequest"
- }
- },
- "description": "A type that contains the fields for the UpdateCampaignBudget request."
- },
- "UpdateCampaignIdentificationRequest": {
- "type": "object",
- "properties": {
- "campaignName": {
- "type": "string",
- "description": "The new seller-defined name for the campaign. This value must be unique for the seller. If you don't want to change the name of the campaign, specify the current campaign name in this field.
You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters."
- },
- "endDate": {
- "type": "string",
- "description": "The date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is omitted, the campaign will have no defined end date, and will not end until the seller makes a decision to end the campaign with an endCampaign call, or if they update the campaign at a later time with an end date.If you want to change only the end date of the campaign, you must specify the current campaign name, set the endDate as desired, and set the startDate to the actual start date of the campaign. This applies if the campaign status is RUNNING or PAUSED. You can retrieve the startDate using the getCampaign method.
Note that if you do not set a new end date in this call, any current endDate value will be set to null. To preserve the currently-set end date, you must specify the value again in your request.
"
- },
- "startDate": {
- "type": "string",
- "description": "The new start date for the campaign, in UTC format (yyyy-MM-ddThh:mm:ssZ).If the campaign status is RUNNING or PAUSED, the startDate must be specified and must be the actual start date of the campaign, even if you are only changing the endDate. You can retrieve the campaign's startDate using the getCampaign method.
On the date specified, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts after this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign.
Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.
"
- }
- },
- "description": "This type specifies the updated name, and start and end dates for an update-campaign request."
- },
- "UpdateCampaignRequest": {
- "type": "object",
- "properties": {
- "audienceCodes": {
- "type": "array",
- "description": "An array of audience codes for the audiences of the email campaign. At least one audience code is required. There is no limit to the number of audience codes that may be entered.
Example: if the current email campaign contains \"audienceCodes\": \"code1\", \"code2\" and the user wishes to add an audience code code3, set the audienceCodes value to \"audienceCodes\": \"code1\", \"code2\", \"code3\".
To retrieve seller audiences, call getAudiences. Use the code values in the response to populate audienceCodes.",
- "items": {
- "type": "string"
- }
- },
- "categoryId": {
- "type": "string",
- "description": "The unique identifier of either an eBay category or a store category.
This field is used if a seller wants to apply an email campaign to a specific eBay category or store category. The categoryType determines whether the categoryId value is an eBay category or store category.
To retrieve eBay categories, use the getCategories or Taxonomy API. To retrieve seller store categories, use the getStore call. Use the categoryId value of the desired category from the results as the value in the request.
itemSelectMode must be set to AUTO in order to use a category ID."
- },
- "categoryType": {
- "type": "string",
- "description": "This field must be set when applying an email campaign to a specific eBay category or store category. The enumeration value used indicates which type of category the categoryId belongs to. For implementation help, refer to eBay API documentation"
- },
- "itemIds": {
- "type": "array",
- "description": "An array of unique identifiers for the listings displayed in an email campaign. Used if the seller wishes to select the eBay listings in the email campaign rather than have eBay automatically select them.
Call getSellerList to retrieve all seller listings. Each Item result contains an ItemID value. Use this value in itemIds to feature that listing.
The maximum number of itemIds for the COUPON campaign type is 4, and for every other campaign type is 10.
itemSelectMode must be set to MANUAL in order to use this field.",
- "items": {
- "type": "string"
- }
- },
- "itemSelectMode": {
- "type": "string",
- "description": "Determines whether listings featured in an email campaign are selected by the seller or by eBay.
If itemSelectMode is set to AUTO, eBay automatically choses listings based on values set for sort, categoryType, categoryId, and priceRange.
If itemSelectMode is set to MANUAL, listings are set by the seller by populating the itemIds array.
Note: itemSelectMode is always set to AUTO for WELCOME email campaigns. For implementation help, refer to eBay API documentation"
- },
- "personalizedMessage": {
- "type": "string",
- "description": "The body of the email campaign. Accepts HTML and CSS. The maximum length is 1000 characters"
- },
- "priceRange": {
- "description": "This container is used if the seller wants to apply the email campaign to listings based on a price range.
The priceRange container consists of the currency, gte, and lte fields.
\"gte\" stands for \"greater than or equal to\" and \"lte\" stands for \"less than or equal to\". Either gte, lte, or both must be used if the seller wishes to include a price range.
Note: Use this object when the itemSelectMode is set to AUTO.",
- "$ref": "#/components/schemas/PriceRange"
- },
- "promotionId": {
- "type": "string",
- "description": "The ID of the promotion used for an email campaign if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT, and promotionSelectModeEnum is set to MANUAL.
To find a promotion, call getPromotions to retrieve a list of the seller's promotions. Use the promotionId from an individual PromotionDetail result for the request."
- },
- "promotionSelectModeEnum": {
- "type": "string",
- "description": "The selection mode for the promotion used. If set to AUTO, eBay will choose the promotion to include in the email campaign. If set to MANUAL, the seller must specify the promotion in the promotionId field.
This field is required if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT. For implementation help, refer to eBay API documentation"
- },
- "scheduleDate": {
- "type": "string",
- "description": "The date and time that the email campaign newsletter will be sent, given in UTC format. Example: 2023-05-20T03:13:35Z
This field should be used if the seller wishes to send the email campaign on a future date. If no scheduleDate is set, the email campaign will send once it is created or updated."
- },
- "sort": {
- "type": "string",
- "description": "The sort rule is used to display the listings featured in the email campaign.
Sort rules are only used if itemSelectMode is set to AUTO. If itemSelectMode is MANUAL, listings are displayed in the order in which they are listed in the itemIds array.
The following sort rules are available:ENDING_FIRST displays listings by ending date, from soonest to latest.LOWEST_PRICED displays listings by price, from lowest to highest.HIGHEST_PRICED displays listings by price, from highest to lowest.NEWLY_LISTED displays listings by date listed, with the newest first.
The default sort rule is NEWLY_LISTED. For implementation help, refer to eBay API documentation"
- },
- "subject": {
- "type": "string",
- "description": "The email campaign subject. The maximum length is 70 characters."
- }
- },
- "description": "The update email campaign request payload"
- },
- "UpdateEmailCampaignResponse": {
- "type": "object",
- "properties": {
- "emailCampaignId": {
- "type": "string",
- "description": "The unique eBay-assigned ID to the email campaign that is generated when the email campaign is created."
- },
- "emailCampaignStatus": {
- "type": "string",
- "description": "The email campaign status. See EmailCampaignStatusEnum for a list of email campaign statuses and their descriptions. For implementation help, refer to eBay API documentation"
- }
- }
- },
- "UpdateKeywordByKeywordIdRequest": {
- "type": "object",
- "properties": {
- "bid": {
- "description": "This container is used to set or change the bid percentage for the keyword. Each time a listing is retrieved in search results using this keyword and clicked on, the seller will be charged this amount. Each click goes toward the daily budget set up for the Cost Per Click (CPC) campaign.",
- "$ref": "#/components/schemas/Amount"
- },
- "keywordId": {
- "type": "string",
- "description": "This field is used to identify the keyword to be updated. The getKeyword method can be used to retrieve keywordId values."
- },
- "keywordStatus": {
- "type": "string",
- "description": "Include this field if you wish to change the status of the keyword. The status value specified here must be different than the keyword's current status. To confirm the current status of a keyword, you can use the getKeyword method.If the status of the ad is currently ACTIVE, you can change status to PAUSED or ARCHIVED. If ad group is currently in PAUSED status, you can change the status back to ACTIVE. Ads that are currently in ARCHIVED status cannot be made ACTIVE again. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A type that contains the fields for the UpdateKeywordByKeywordId request."
- },
- "UpdateKeywordRequest": {
- "type": "object",
- "properties": {
- "bid": {
- "description": "This container is used to set or change the bid for the keyword. Each time a listing is retrieved in search results using this keyword and clicked on, the seller will be charged this amount. Each click goes toward the daily budget set up for the CPC campaign. If the bid is not provided, then the default bid associated with the ad group is used.",
- "$ref": "#/components/schemas/Amount"
- },
- "keywordStatus": {
- "type": "string",
- "description": "Include this field if you wish to change the status of the keyword. The status value specified here must be different than the keyword's current status. To confirm the current status of a keyword, you can use the getKeyword method.
If the status of the ad is currently ACTIVE, you can change status to PAUSED or ARCHIVED. If ad group is currently in PAUSED status, you can change the status back to ACTIVE. Ads that are currently in ARCHIVED status cannot be made ACTIVE again. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A type that contains the fields for the UpdateKeyword request."
- },
- "UpdateKeywordResponse": {
- "type": "object",
- "properties": {
- "errors": {
- "type": "array",
- "description": "This container will be returned if there are one or more issues associated with modifying the corresponding keyword.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "keywordId": {
- "type": "string",
- "description": "This field identifies the keyword that the seller updated, or attempted to update."
- },
- "statusCode": {
- "type": "integer",
- "description": "An HTTP status code is returned for each keyword to indicate the success or failure of updating that keyword.",
- "format": "int32"
- }
- },
- "description": "A type that contains the fields for the UpdateKeyword response."
- },
- "UpdateNegativeKeywordIdRequest": {
- "type": "object",
- "properties": {
- "negativeKeywordId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a negative keyword. This keyword ID will be generated for each successfully created negative keyword."
- },
- "negativeKeywordStatus": {
- "type": "string",
- "description": "A field that defines the status of the negative keyword. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A type that defines the fields used to update a negative keyword."
- },
- "UpdateNegativeKeywordRequest": {
- "type": "object",
- "properties": {
- "negativeKeywordStatus": {
- "type": "string",
- "description": "A field that defines the status of the negative keyword. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A type that contains the fields for the UpdateNegativeKeyword request."
- },
- "UpdateNegativeKeywordResponse": {
- "type": "object",
- "properties": {
- "errors": {
- "type": "array",
- "description": "A container that will be returned if there are one or more issues associated with modifying the corresponding negative keyword.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- },
- "negativeKeywordId": {
- "type": "string",
- "description": "A unique eBay-assigned ID for a negative keyword. This keyword ID will be generated for each successfully created negative keyword."
- },
- "statusCode": {
- "type": "integer",
- "description": "An HTTP status code that indicates the success or failure of updating that negative keyword.",
- "format": "int32"
- }
- },
- "description": "A type that contains the fields for the UpdateNegativeKeyword response."
- }
- },
- "securitySchemes": {
- "api_auth": {
- "type": "oauth2",
- "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
- "flows": {
- "clientCredentials": {
- "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
- "scopes": {
- "https://api.ebay.com/oauth/api_scope": "View public data from eBay"
- }
- },
- "authorizationCode": {
- "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
- "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
- "scopes": {
- "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly": "View your eBay marketing activities, such as ad campaigns and listing promotions",
- "https://api.ebay.com/oauth/api_scope/sell.marketing": "View and manage your eBay marketing activities, such as ad campaigns and listing promotions"
}
- }
}
- }
}
- }
}
\ No newline at end of file
diff --git a/specs/sell_metadata_v1_oas3.json b/specs/sell_metadata_v1_oas3.json
index 8e54487a..342c738f 100644
--- a/specs/sell_metadata_v1_oas3.json
+++ b/specs/sell_metadata_v1_oas3.json
@@ -1,1470 +1,4832 @@
{
- "openapi": "3.0.0",
- "info": {
- "title": "Metadata API",
- "description": "The Metadata API has operations that retrieve configuration details pertaining to the different eBay marketplaces. In addition to marketplace information, the API also has operations that get information that helps sellers list items on eBay.",
- "contact": {
- "name": "eBay Inc,"
- },
- "license": {
- "name": "eBay API License Agreement",
- "url": "https://developer.ebay.com/join/api-license-agreement"
- },
- "version": "v1.7.1"
- },
- "servers": [
- {
- "url": "https://api.ebay.com{basePath}",
- "description": "Production",
- "variables": {
- "basePath": {
- "default": "/sell/metadata/v1"
- }
- }
- }
- ],
- "paths": {
- "/marketplace/{marketplace_id}/get_automotive_parts_compatibility_policies": {
- "get": {
- "tags": [
- "marketplace"
- ],
- "description": "This method returns the eBay policies that define how to list automotive parts compatibility items in the categories of the specified marketplace.
By default, this method returns all categories that support parts compatibility. You can limit the size of the result set by using the filter query parameter to specify only the category IDs you want to review.
Note: To return policy information for the eBay US marketplace, specify EBAY_MOTORS_US as the path parameter for marketplace_id.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.
If you specify a valid marketplace ID but that marketplace does not contain policy information, or if you filter out all results, a 204 No content status code is returned with an empty response body.",
- "operationId": "getAutomotivePartsCompatibilityPolicies",
- "parameters": [
- {
- "name": "filter",
- "in": "query",
- "description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned. Use the Taxonomy API to retrieve category ID values.
When you specify a categoryId value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below the at parent node.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{183521|183523|183524}
Note: URL-encoding of the parameter list is no longer required.",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "marketplace_id",
- "in": "path",
- "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
Note: Only the following eBay marketplaces support automotive parts compatibility: - EBAY_MOTORS_US
- EBAY_AU
- EBAY_CA
- EBAY_DE
- EBAY_ES
- EBAY_FR
- EBAY_GB
- EBAY_IT
",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Accept-Encoding",
- "in": "header",
- "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/AutomotivePartsCompatibilityPolicyResponse"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "46002": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
- },
- "46003": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified categoryId was not found for the marketplace."
- },
- "46004": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "Only 50 Category IDs specified in the filter are considered."
- }
- }
- }
- },
- "204": {
- "description": "No content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "46001": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified marketplace ID was not found."
- }
- }
- }
- },
- "404": {
- "description": "Not found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "46000": {
- "domain": "API_METADATA",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
- }
- }
+ "openapi": "3.0.0",
+ "info": {
+ "title": "Metadata API",
+ "description": "The Metadata API has operations that retrieve configuration details pertaining to the different eBay marketplaces. In addition to marketplace information, the API also has operations that get information that helps sellers list items on eBay.",
+ "contact": {
+ "name": "eBay Inc,"
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope"
- ]
- }
- ]
- }
- },
- "/marketplace/{marketplace_id}/get_extended_producer_responsibility_policies": {
- "get": {
- "tags": [
- "marketplace"
- ],
- "description": "This method returns the Extended Producer Responsibility policies for one, multiple, or all eBay categories in an eBay marketplace.
The identifier of the eBay marketplace is passed in as a path parameter, and unless one or more eBay category IDs are passed in through the filter query parameter, this method will return metadata on every applicable category for the specified marketplace.
Note: Currently, the Extended Producer Responsibility policies are only applicable to a limited number of categories.
Note: Extended Producer Responsibility IDs are no longer set at the listing level so category-level metadata is no longer returned. Instead, sellers will provide/manage these IDs at the account level by going to Account Settings.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.",
- "operationId": "getExtendedProducerResponsibilityPolicies",
- "parameters": [
- {
- "name": "filter",
- "in": "query",
- "description": "A query parameter that can be used to limit the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree that should be returned.
When a categoryId value is specified, the returned category tree includes the policies for that parent node, as well as the policies for any child nodes below that parent node.
Pass in the categoryId values using a URL-encoded, pipe-separated ('|') list. For example:
filter=categoryIds%3A%7B100%7C101%7C102%7D
Maximum: 50",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "marketplace_id",
- "in": "path",
- "description": "This path parameter specifies the eBay marketplace for which policy information shall be retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Accept-Encoding",
- "in": "header",
- "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ExtendedProducerResponsibilityPolicyResponse"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "46002": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
- },
- "46003": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified categoryId was not found for the marketplace."
- },
- "46004": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "Only 50 Category IDs specified in the filter are considered."
- }
- }
- }
- },
- "204": {
- "description": "No content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "46001": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified marketplace ID was not found."
- }
- }
- }
- },
- "404": {
- "description": "Not found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "46000": {
- "domain": "API_METADATA",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
- }
- }
- }
- }
+ "license": {
+ "name": "eBay API License Agreement",
+ "url": "https://developer.ebay.com/join/api-license-agreement"
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope"
- ]
- }
- ]
- }
+ "version": "v1.12.1"
},
- "/marketplace/{marketplace_id}/get_hazardous_materials_labels": {
- "get": {
- "tags": [
- "marketplace"
- ],
- "description": "This method returns hazardous materials label information for the specified eBay marketplace. The information includes IDs, descriptions, and URLs (as applicable) for the available signal words, statements, and pictograms. The returned statements are localized for the default langauge of the marketplace. If a marketplace does not support hazardous materials label information, an error is returned.
This information is used by the seller to add hazardous materials label related information to their listings (see Specifying hazardous material related information).
",
- "operationId": "getHazardousMaterialsLabels",
- "parameters": [
- {
- "name": "marketplace_id",
- "in": "path",
- "description": "This path parameter specifies the eBay marketplace for which hazardous materials label information shall be retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/HazardousMaterialDetailsResponse"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "46001": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified marketplace ID was not found."
+ "servers": [
+ {
+ "url": "https://api.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/metadata/v1"
}
- }
}
- },
- "404": {
- "description": "Not found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "46000": {
- "domain": "API_METADATA",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
- }
- }
+ }
+ ],
+ "paths": {
+ "/marketplace/{marketplace_id}/get_automotive_parts_compatibility_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns the eBay policies that define how to list automotive parts compatibility items in the categories of the specified marketplace.
By default, this method returns all categories that support parts compatibility. You can limit the size of the result set by using the filter query parameter to specify only the category IDs you want to review.
Note: To return policy information for the eBay US marketplace, specify EBAY_MOTORS_US as the path parameter for marketplace_id.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.
If you specify a valid marketplace ID but that marketplace does not contain policy information, or if you filter out all results, a 204 No content status code is returned with an empty response body.",
+ "operationId": "getAutomotivePartsCompatibilityPolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned. Use the Taxonomy API to retrieve category ID values.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{183521|183523|183524}
Note: URL-encoding of the parameter list is no longer required.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
Note: Only the following eBay marketplaces support automotive parts compatibility: - EBAY_MOTORS_US
- EBAY_AU
- EBAY_CA
- EBAY_DE
- EBAY_ES
- EBAY_FR
- EBAY_GB
- EBAY_IT
",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Encoding",
+ "in": "header",
+ "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AutomotivePartsCompatibilityPolicyResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only 50 Category IDs specified in the filter are considered."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope"
- ]
- }
- ]
- }
- },
- "/marketplace/{marketplace_id}/get_item_condition_policies": {
- "get": {
- "tags": [
- "marketplace"
- ],
- "description": "This method returns item condition metadata on one, multiple, or all eBay categories on an eBay marketplace. This metadata consists of the different item conditions (with IDs) that an eBay category supports, and a boolean to indicate if an eBay category requires an item condition.
If applicable, this metadata also shows the different condition descriptors (with IDs) that an eBay category supports.
Note: Currently, condition grading is only applicable to the following trading card categories: - Non-Sport Trading Card Singles
- CCG Individual Cards
- Sports Trading Cards Singles
The identifier of the eBay marketplace is passed in as a path parameter, and unless one or more eBay category IDs are passed in through the filter query parameter, this method will return metadata on every single category for the specified marketplace. If you only want to view item condition metadata for one eBay category or a select group of eBay categories, you can pass in up to 50 eBay category ID through the filter query parameter.
Important: Certified - Refurbished-eligible sellers, and sellers who are eligible to list with the new values (EXCELLENT_REFURBISHED, VERY_GOOD_REFURBISHED, and GOOD_REFURBISHED) must use an OAuth token created with the authorization code grant flow and https://api.ebay.com/oauth/api_scope/sell.inventory scope in order to retrieve the refurbished conditions for the relevant categories.
See the eBay Refurbished Program - Category and marketplace support topic for the categories and marketplaces that support these refurbished conditions
These restricted item conditions will not be returned if an OAuth token created with the client credentials grant flow and https://api.ebay.com/oauth/api_scope scope is used, or if any seller is not eligible to list with that item condition.
See the Specifying OAuth scopes topic for more information about specifying scopes.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.",
- "operationId": "getItemConditionPolicies",
- "parameters": [
- {
- "name": "filter",
- "in": "query",
- "description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned.
When you specify a categoryId value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{100|101|102}
Note that you must URL-encode the parameter list, which results in the following filter for the above example:
filter=categoryIds%3A%7B100%7C101%7C102%7D",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "marketplace_id",
- "in": "path",
- "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Accept-Encoding",
- "in": "header",
- "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ItemConditionPolicyResponse"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "46002": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
- },
- "46003": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified categoryId was not found for the marketplace."
- },
- "46004": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "Only 50 Category IDs specified in the filter are considered."
- }
- }
- }
- },
- "204": {
- "description": "No content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "46001": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified marketplace ID was not found."
- }
- }
- }
- },
- "404": {
- "description": "Not found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "46000": {
- "domain": "API_METADATA",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
- }
- }
+ "/marketplace/{marketplace_id}/get_category_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns eBay category policy metadata for all leaf categories on the specified marketplace.By default, this method returns metadata on all leaf categories. You can limit the size of the result set by using the filter query parameter to specify only the leaf category IDs you want to review.
If you specify a valid marketplace ID but that marketplace does not contain policy information, or if you filter out all results, a successful call returns a 204 No content status code with an empty response body.
",
+ "operationId": "getCategoryPolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This query parameter limits the response by only returning metadata for the specified leaf categories. Supply the categoryId for one or more leaf categories. You can verify if a category is a leaf category by using the Taxonomy API and looking for a \"leafCategory\": true tag.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{3767|171784}",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CategoryPolicyResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only {maxCategoryIdsAllowed} Category IDs are allowed in the 'filter' parameter."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope",
- "https://api.ebay.com/oauth/api_scope/sell.inventory"
- ]
- }
- ]
- }
- },
- "/marketplace/{marketplace_id}/get_listing_structure_policies": {
- "get": {
- "tags": [
- "marketplace"
- ],
- "description": "This method returns the eBay policies that define the allowed listing structures for the categories of a specific marketplace. The listing-structure policies currently pertain to whether or not you can list items with variations.
By default, this method returns the entire category tree for the specified marketplace. You can limit the size of the result set by using the filter query parameter to specify only the category IDs you want to review.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.",
- "operationId": "getListingStructurePolicies",
- "parameters": [
- {
- "name": "filter",
- "in": "query",
- "description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned.
When you specify a categoryId value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{100|101|102}
Note that you must URL-encode the parameter list, which results in the following filter for the above example:
filter=categoryIds%3A%7B100%7C101%7C102%7D",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "marketplace_id",
- "in": "path",
- "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Accept-Encoding",
- "in": "header",
- "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ListingStructurePolicyResponse"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "46002": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
- },
- "46003": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified categoryId was not found for the marketplace."
- },
- "46004": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "Only 50 Category IDs specified in the filter are considered."
- }
- }
- }
- },
- "204": {
- "description": "No content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "46001": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified marketplace ID was not found."
- }
- }
- }
- },
- "404": {
- "description": "Not found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "46000": {
- "domain": "API_METADATA",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
- }
- }
+ "/marketplace/{marketplace_id}/get_classified_ad_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns eBay classified ad policy metadata for all leaf categories on the specified marketplace.By default, this method returns metadata on all leaf categories. You can limit the size of the result set by using the filter query parameter to specify only the leaf category IDs you want to review.
If you specify a valid marketplace ID but that marketplace does not contain policy information, or if you filter out all results, a successful call returns a 204 No content status code with an empty response body.
Note: This method does not support classified ads for eBay US Motors categories (EBAY_MOTORS_US). For eBay Motors Pro users, use getMotorsListingPolicies.
",
+ "operationId": "getClassifiedAdPolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This query parameter limits the response by only returning metadata for the specified leaf categories. Supply the categoryId for one or more leaf categories. You can verify if a category is a leaf category by using the Taxonomy API and looking for a \"leafCategory\": true tag.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example:filter=categoryIds:{3767|171784}",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See MarketplaceIdEnum for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ClassifiedAdPolicyResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only {maxCategoryIdsAllowed} Category IDs are allowed in the 'filter' parameter."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope"
- ]
- }
- ]
- }
- },
- "/marketplace/{marketplace_id}/get_negotiated_price_policies": {
- "get": {
- "tags": [
- "marketplace"
- ],
- "description": "This method returns the eBay policies that define the supported negotiated price features (like \"best offer\") for the categories of a specific marketplace.
By default, this method returns the entire category tree for the specified marketplace. You can limit the size of the result set by using the filter query parameter to specify only the category IDs you want to review.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.",
- "operationId": "getNegotiatedPricePolicies",
- "parameters": [
- {
- "name": "filter",
- "in": "query",
- "description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned.
When you specify a categoryId value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{100|101|102}
Note that you must URL-encode the parameter list, which results in the following filter for the above example:
filter=categoryIds%3A%7B100%7C101%7C102%7D",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "marketplace_id",
- "in": "path",
- "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Accept-Encoding",
- "in": "header",
- "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/NegotiatedPricePolicyResponse"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "46002": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
- },
- "46003": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified categoryId was not found for the marketplace."
- },
- "46004": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "Only 50 Category IDs specified in the filter are considered."
- }
- }
- }
- },
- "204": {
- "description": "No content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "46001": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified marketplace ID was not found."
- }
- }
- }
- },
- "404": {
- "description": "Not found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "46000": {
- "domain": "API_METADATA",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
- }
- }
+ "/marketplace/{marketplace_id}/get_currencies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns the default currency used by the eBay marketplace specified in the request. This is the currency that the seller should use when providing price data for this marketplace through listing APIs.",
+ "operationId": "getCurrencies",
+ "parameters": [
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which currency information is retrieved.
See the MarketplaceIdEnum type for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada and French Belgium marketplaces.
Follow the instructions below to retrieve metadata for these marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE.
Note: If EBAY_BE is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the Dutch Belgium marketplace. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA and include the Accept-Language header with a value of fr-CA. Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.
",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetCurrenciesResponse"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope"
- ]
- }
- ]
- }
- },
- "/marketplace/{marketplace_id}/get_return_policies": {
- "get": {
- "tags": [
- "marketplace"
- ],
- "description": "This method returns the eBay policies that define whether or not you must include a return policy for the items you list in the categories of a specific marketplace, plus the guidelines for creating domestic and international return policies in the different eBay categories.
By default, this method returns the entire category tree for the specified marketplace. You can limit the size of the result set by using the filter query parameter to specify only the category IDs you want to review.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.",
- "operationId": "getReturnPolicies",
- "parameters": [
- {
- "name": "filter",
- "in": "query",
- "description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned.
When you specify a categoryId value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{100|101|102}
Note that you must URL-encode the parameter list, which results in the following filter for the above example:
filter=categoryIds%3A%7B100%7C101%7C102%7D",
- "required": false,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "marketplace_id",
- "in": "path",
- "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
- "required": true,
- "schema": {
- "type": "string"
- }
- },
- {
- "name": "Accept-Encoding",
- "in": "header",
- "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
- "required": false,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ReturnPolicyResponse"
- }
- }
- },
- "x-response-codes": {
- "errors": {
- "46002": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
- },
- "46003": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified categoryId was not found for the marketplace."
- },
- "46004": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "Only 50 Category IDs specified in the filter are considered."
- }
- }
- }
- },
- "204": {
- "description": "No content"
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "46001": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "The specified marketplace ID was not found."
- }
- }
- }
- },
- "404": {
- "description": "Not found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "46000": {
- "domain": "API_METADATA",
- "category": "APPLICATION",
- "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
- }
- }
+ "/marketplace/{marketplace_id}/get_extended_producer_responsibility_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns the Extended Producer Responsibility policies for one, multiple, or all eBay categories in an eBay marketplace.
The identifier of the eBay marketplace is passed in as a path parameter, and unless one or more eBay category IDs are passed in through the filter query parameter, this method will return metadata on every applicable category for the specified marketplace.
Note: Currently, the Extended Producer Responsibility policies are only applicable to a limited number of categories.
Note: Extended Producer Responsibility IDs are no longer set at the listing level so category-level metadata is no longer returned. Instead, sellers will provide/manage these IDs at the account level by going to Account Settings.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.",
+ "operationId": "getExtendedProducerResponsibilityPolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "A query parameter that can be used to limit the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree that should be returned.
When a categoryId value is specified, the returned category tree includes the policies for that parent node, as well as the policies for any child nodes below that parent node.
Pass in the categoryId values using a URL-encoded, pipe-separated ('|') list. For example:
filter=categoryIds%3A%7B100%7C101%7C102%7D
Maximum: 50",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information shall be retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Encoding",
+ "in": "header",
+ "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ExtendedProducerResponsibilityPolicyResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only 50 Category IDs specified in the filter are considered."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope"
- ]
- }
- ]
- }
- },
- "/country/{countryCode}/sales_tax_jurisdiction": {
- "get": {
- "tags": [
- "country"
- ],
- "description": "This method retrieves all sales-tax jurisdictions for the country specified in the countryCode path parameter. Countries with valid sales-tax jurisdictions are Canada and the US.
The response from this call tells you the jurisdictions for which a seller can configure tax tables. Although setting up tax tables is optional, you can use the createOrReplaceSalesTax method in the Account API call to configure the tax tables for the jurisdictions into which you sell.
Note: Sales-tax tables are only available for the US (EBAY_US) and Canada (EBAY_CA) marketplaces.
Important! In the US, eBay now calculates, collects, and remits sales tax to the proper taxing authorities in all 50 states and Washington, DC. Sellers can no longer specify sales-tax rates for these jurisdictions using a tax table.
However, sellers may continue to use a sales-tax table to set rates for the following US territories:
- American Samoa (AS)
- Guam (GU)
- Northern Mariana Islands (MP)
- Palau (PW)
- US Virgin Islands (VI)
For additional information, refer to
Taxes and import charges.
Note: Sales-tax tables are available only for the US and Canada marketplaces. Therefore, the only supported values are:",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/SalesTaxJurisdictions"
- }
- }
- }
- },
- "400": {
- "description": "Bad Request",
- "x-response-codes": {
- "errors": {
- "45400": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "Invalid input. {additionalInfo}"
- },
- "45401": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "Invalid {fieldName}."
- },
- "45402": {
- "domain": "API_METADATA",
- "category": "REQUEST",
- "description": "Tax table not supported for {fieldName}."
- }
- }
- }
- },
- "404": {
- "description": "Not Found"
- },
- "500": {
- "description": "Internal Server Error",
- "x-response-codes": {
- "errors": {
- "45500": {
- "domain": "API_METADATA",
- "category": "APPLICATION",
- "description": "System error."
- }
- }
+ "/marketplace/{marketplace_id}/get_hazardous_materials_labels": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns hazardous materials label information for the specified eBay marketplace. The information includes IDs, descriptions, and URLs (as applicable) for the available signal words, statements, and pictograms. The returned statements are localized for the default language of the marketplace. If a marketplace does not support hazardous materials label information, no response payload is returned, but only a 204 No content status code.This information is used by the seller to add hazardous materials label related information to their listings (see Specifying hazardous material related information).
",
+ "operationId": "getHazardousMaterialsLabels",
+ "parameters": [
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which hazardous materials label information shall be retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HazardousMaterialDetailsResponse"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "security": [
- {
- "api_auth": [
- "https://api.ebay.com/oauth/api_scope"
- ]
- }
- ]
- }
- }
- },
- "components": {
- "schemas": {
- "AutomotivePartsCompatibilityPolicy": {
- "type": "object",
- "properties": {
- "categoryId": {
- "type": "string",
- "description": "The category ID to which the automotive-parts-compatibility policies apply."
- },
- "categoryTreeId": {
- "type": "string",
- "description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree.
A category tree is a hierarchical framework of eBay categories that begins at the root node of the tree and extends to include all the child nodes in the tree. Each child node in the tree is an eBay category that is represented by a unique categoryId value. Within a category tree, the root node has no parent node and leaf nodes are nodes that have no child nodes."
- },
- "compatibilityBasedOn": {
- "type": "string",
- "description": "Indicates whether the category supports parts compatibility by either ASSEMBLY or by SPECIFICATION. For implementation help, refer to eBay API documentation"
- },
- "compatibleVehicleTypes": {
- "type": "array",
- "description": "Indicates the compatibility classification of the part based on high-level vehicle types.",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
- }
- },
- "maxNumberOfCompatibleVehicles": {
- "type": "integer",
- "description": "Specifies the maximum number of compatible vehicle-applications allowed per item.",
- "format": "int32"
- }
- }
- },
- "AutomotivePartsCompatibilityPolicyResponse": {
- "type": "object",
- "properties": {
- "automotivePartsCompatibilityPolicies": {
- "type": "array",
- "description": "A list of category IDs and the automotive-parts-compatibility policies for each of the listed categories.",
- "items": {
- "$ref": "#/components/schemas/AutomotivePartsCompatibilityPolicy"
- }
- },
- "warnings": {
- "type": "array",
- "description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- },
- "Error": {
- "type": "object",
- "properties": {
- "category": {
- "type": "string",
- "description": "The category type for this error or warning. It takes an ErrorCategory object which can have one of three values:Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as \"Seller does not ship item to Antarctica\" or \"Buyer ineligible to purchase an alcoholic item\". Business errors are not syntactical input errors.Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.
"
- },
- "domain": {
- "type": "string",
- "description": "Name of the domain containing the service or application."
- },
- "errorId": {
- "type": "integer",
- "description": "A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.",
- "format": "int32"
- },
- "inputRefIds": {
- "type": "array",
- "description": "Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.",
- "items": {
- "type": "string"
- }
- },
- "longMessage": {
- "type": "string",
- "description": "An expanded version of message that should be around 100-200 characters long, but is not required to be such."
- },
- "message": {
- "type": "string",
- "description": "An end user and app developer friendly device agnostic message. It explains what the error or warning is, and how to fix it (in a general sense). Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale."
- },
- "outputRefIds": {
- "type": "array",
- "description": "Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.",
- "items": {
- "type": "string"
- }
- },
- "parameters": {
- "type": "array",
- "description": "This optional complex field type contains a list of one or more context-specific ErrorParameter objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.",
- "items": {
- "$ref": "#/components/schemas/ErrorParameter"
+ "/marketplace/{marketplace_id}/get_item_condition_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns item condition metadata on one, multiple, or all eBay categories on an eBay marketplace. This metadata consists of the different item conditions (with IDs) that an eBay category supports, and a boolean to indicate if an eBay category requires an item condition.
If applicable, this metadata also shows the different condition descriptors (with IDs) that an eBay category supports.
Note: Currently, condition grading is only applicable to the following trading card categories: - Non-Sport Trading Card Singles
- CCG Individual Cards
- Sports Trading Cards Singles
The identifier of the eBay marketplace is passed in as a path parameter, and unless one or more eBay category IDs are passed in through the filter query parameter, this method will return metadata on every single category for the specified marketplace. If you only want to view item condition metadata for one eBay category or a select group of eBay categories, you can pass in up to 50 eBay category ID through the filter query parameter.
Important: Certified - Refurbished-eligible sellers, and sellers who are eligible to list with the new values (EXCELLENT_REFURBISHED, VERY_GOOD_REFURBISHED, and GOOD_REFURBISHED) must use an OAuth token created with the authorization code grant flow and https://api.ebay.com/oauth/api_scope/sell.inventory scope in order to retrieve the refurbished conditions for the relevant categories.
Refurbished item conditions are only supported in the Australia, Canada, French Canada, Germany, France, Italy, UK, and US marketplaces. See the eBay Refurbished Program page in help center for the categories that support refurbished conditions.
These restricted item conditions will not be returned if an OAuth token created with the client credentials grant flow and https://api.ebay.com/oauth/api_scope scope is used, or if any seller is not eligible to list with that item condition.
See the Specifying OAuth scopes topic for more information about specifying scopes.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.",
+ "operationId": "getItemConditionPolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned.
When you specify a categoryId value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{100|101|102}
Note that you must URL-encode the parameter list, which results in the following filter for the above example:
filter=categoryIds%3A%7B100%7C101%7C102%7D",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Encoding",
+ "in": "header",
+ "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ItemConditionPolicyResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only 50 Category IDs specified in the filter are considered."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope",
+ "https://api.ebay.com/oauth/api_scope/sell.inventory"
+ ]
+ }
+ ]
}
- },
- "subdomain": {
- "type": "string",
- "description": "Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain."
- }
- },
- "description": "A container that defines the elements of error and warning messages."
- },
- "ErrorParameter": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "Name of the entity that threw the error."
- },
- "value": {
- "type": "string",
- "description": "A description of the error."
- }
},
- "description": "Container for a error parameter."
- },
- "ExtendedProducerResponsibility": {
- "type": "object",
- "properties": {
- "enabledForVariations": {
- "type": "boolean",
- "description": "An indication of whether the attribute can be enabled for listing variations.
If the value is true, the attribute may be specified at the variation level."
- },
- "name": {
- "type": "string",
- "description": "The name of the attribute included in the policy. For implementation help, refer to eBay API documentation"
- },
- "usage": {
- "type": "string",
- "description": "The usage guidelines for the attribute, in the specified marketplace. For implementation help, refer to eBay API documentation"
- }
- },
- "description": "A type that defines the attributes of an Extended Producer Responsibility policy."
- },
- "ExtendedProducerResponsibilityPolicy": {
- "type": "object",
- "properties": {
- "categoryId": {
- "type": "string",
- "description": "The unique identifier for the category under which the policy applies."
- },
- "categoryTreeId": {
- "type": "string",
- "description": "The unique identifier for the category tree under which the policy applies."
- },
- "supportedAttributes": {
- "type": "array",
- "description": "The details regarding the attributes included in the policy, such as their usage guidelines and whether they can be specified at the listing variation level.",
- "items": {
- "$ref": "#/components/schemas/ExtendedProducerResponsibility"
+ "/marketplace/{marketplace_id}/get_listing_structure_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns the eBay policies that define the allowed listing structures for the categories of a specific marketplace. The listing-structure policies currently pertain to whether or not you can list items with variations.
By default, this method returns the entire category tree for the specified marketplace. You can limit the size of the result set by using the filter query parameter to specify only the category IDs you want to review.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.",
+ "operationId": "getListingStructurePolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned.
When you specify a categoryId value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{100|101|102}
Note that you must URL-encode the parameter list, which results in the following filter for the above example:
filter=categoryIds%3A%7B100%7C101%7C102%7D",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Encoding",
+ "in": "header",
+ "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ListingStructurePolicyResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only 50 Category IDs specified in the filter are considered."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "description": "A type that defines the Extended Producer Responsibility policy."
- },
- "ExtendedProducerResponsibilityPolicyResponse": {
- "type": "object",
- "properties": {
- "extendedProducerResponsibilities": {
- "type": "array",
- "description": "An array of response fields detailing the Extended Producer Responsibility policies supported for the specified marketplace.",
- "items": {
- "$ref": "#/components/schemas/ExtendedProducerResponsibilityPolicy"
- }
- },
- "warnings": {
- "type": "array",
- "description": "A collection of warnings generated for the request.",
- "items": {
- "$ref": "#/components/schemas/Error"
+ "/marketplace/{marketplace_id}/get_listing_type_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns eBay listing type policy metadata for all leaf categories on the specified marketplace. By default, this method returns metadata on all leaf categories. You can limit the size of the result set by using the filter query parameter to specify only the leaf category IDs you want to review.
If you specify a valid marketplace ID but that marketplace does not contain policy information, or if you filter out all results, a successful call returns a 204 No content status code with an empty response body.
",
+ "operationId": "getListingTypePolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This query parameter limits the response by only returning metadata for the specified leaf categories. Supply the categoryId for one or more leaf categories. You can verify if a category is a leaf category by using the Taxonomy API and looking for a \"leafCategory\": true tag.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{3767|171784}",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ListingTypePoliciesResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only {maxCategoryIdsAllowed} Category IDs are allowed in the 'filter' parameter."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
- },
- "description": "A type that defines the response fields for the getExtendedProducerResponsibilityPolicies method."
- },
- "HazardStatement": {
- "type": "object",
- "properties": {
- "statementId": {
- "type": "string",
- "description": "The identifier of the statement. For sample values, see Hazard statement sample values."
- },
- "statementDescription": {
- "type": "string",
- "description": "The description of the statement localized to the default language of the marketplace. For sample values, see Hazard statement sample values."
- }
},
- "description": "A type that describes hazard statements for hazardous materials labels"
- },
- "HazardousMaterialDetailsResponse": {
- "type": "object",
- "properties": {
- "signalWords": {
- "type": "array",
- "description": "This array contains available hazardous materials signal words for the specified marketplace.",
- "items": {
- "$ref": "#/components/schemas/SignalWord"
- }
- },
- "statements": {
- "type": "array",
- "description": "This array contains available hazardous materials hazard statements for the specified marketplace.",
- "items": {
- "$ref": "#/components/schemas/HazardStatement"
- }
- },
- "pictograms": {
- "type": "array",
- "description": "This array contains of available hazardous materials hazard pictograms for the specified marketplace.",
- "items": {
- "$ref": "#/components/schemas/Pictogram"
+ "/marketplace/{marketplace_id}/get_motors_listing_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns eBay Motors policy metadata for all leaf categories on the specified marketplace. By default, this method returns metadata on all leaf categories. You can limit the size of the result set by using the filter query parameter to specify only the leaf category IDs you want to review.
If you specify a valid marketplace ID but that marketplace does not contain policy information, or if you filter out all results, a successful call returns a 204 No content status code with an empty response body.
Note: To return policy information for eBay US Motors categories, specify marketplace_id as EBAY_MOTORS_US.
",
+ "operationId": "getMotorsListingPolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This query parameter limits the response by only returning metadata for the specified leaf categories. Supply the categoryId for one or more leaf categories. You can verify if a category is a leaf category by using the Taxonomy API and looking for a \"leafCategory\": true tag.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{3767|171784}",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/MotorsListingPoliciesResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only {maxCategoryIdsAllowed} Category IDs are allowed in the 'filter' parameter."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "description": "A type that defines the response fields for the getHazardousMaterialsLabels method."
- },
- "ItemCondition": {
- "type": "object",
- "properties": {
- "conditionDescription": {
- "type": "string",
- "description": "The human-readable label for the condition (e.g., \"New\"). This value is typically localized for each site.
Note that the display name can vary by category. For example, the description for condition ID 1000 could be called \"New: with Tags\" in one category and \"Brand New\" in another. For details on condition IDs and descriptions, see Item condition ID and name values."
- },
- "conditionDescriptors": {
- "type": "array",
- "description": "This array contains the possible condition descriptors and condition descriptor values applicable for the specified category. It also returns usage requirements, maximum length, cardinality, and help text.
Note: This array is only returned for categories that support condition descriptors.",
- "items": {
- "$ref": "#/components/schemas/ItemConditionDescriptor"
+ "/marketplace/{marketplace_id}/get_negotiated_price_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns the eBay policies that define the supported negotiated price features (like \"best offer\") for the categories of a specific marketplace.
By default, this method returns the entire category tree for the specified marketplace. You can limit the size of the result set by using the filter query parameter to specify only the category IDs you want to review.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.",
+ "operationId": "getNegotiatedPricePolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned.
When you specify a categoryId value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{100|101|102}
Note that you must URL-encode the parameter list, which results in the following filter for the above example:
filter=categoryIds%3A%7B100%7C101%7C102%7D",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Encoding",
+ "in": "header",
+ "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/NegotiatedPricePolicyResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only 50 Category IDs specified in the filter are considered."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- },
- "conditionHelpText": {
- "type": "string",
- "description": "A detailed description of the condition denoted by the conditionID and conditionDescription. "
- },
- "conditionId": {
- "type": "string",
- "description": "The ID value of the selected item condition. For information on the supported condition ID values, see Item condition ID and name values."
- },
- "usage": {
- "type": "string",
- "description": "The value returned in this field indicates if there are any usage restrictions or requirements for the corresponding item condition in the corresponding category.
Note: Currently, the only supported value is 'RESTRICTED', and this field will only be returned for the following conditions: 2000, 2010, 2020, 2030. Sellers must be pre-approved to use any of these item conditions. For implementation help, refer to eBay API documentation"
- }
},
- "description": "Note: In all eBay marketplaces, Condition ID 2000 now maps to an item condition of 'Certified Refurbished', and not 'Manufacturer Refurbished'. To list an item as 'Certified Refurbished', a seller must be pre-qualified by eBay for this feature. Any seller who is not eligible for this feature will be blocked if they try to create a new listing or revise an existing listing with this item condition. Any active listings on any eBay marketplace that had 'Manufacturer Refurbished' as the item condition should have been automatically updated by eBay to the 'Seller Refurbished' item condition (Condition ID 2500).
Any seller that is interested in eligibility requirements to list with 'Certified Refurbished' should see the Certified refurbished program page in Seller Center. "
- },
- "ItemConditionDescriptor": {
- "type": "object",
- "properties": {
- "conditionDescriptorConstraint": {
- "description": "This container shows the constraints on a condition descriptor, such as the maximum length, default condition descriptor value ID, cardinality, mode, usage, and applicable descriptor IDs.",
- "$ref": "#/components/schemas/ItemConditionDescriptorConstraint"
- },
- "conditionDescriptorHelpText": {
- "type": "string",
- "description": "A description of the condition descriptor that directs a user to its condition descriptor values.
For example, the help text for Card Condition is Select ungraded condition."
- },
- "conditionDescriptorId": {
- "type": "string",
- "description": "The unique identification number of a condition descriptor associated with with a conditionDescriptorName.
For example, 40001 is the ID for Card Condition.
These IDs are used in the addItem family of calls of the Trading API to provide condition descriptor names for the item. These IDs are used by the inventoryItem family of calls of the Inventory API to provide condition descriptor names for the item."
- },
- "conditionDescriptorName": {
- "type": "string",
- "description": "The human-readable label for the condition descriptor associated with the conditionDescriptorID.
For example, Card Condition is the condition descriptor name for ID 40001"
- },
- "conditionDescriptorValues": {
- "type": "array",
- "description": "This array shows the possible values that map to the corresponding conditionDescriptorName values. Constraint information and help text are also shown for each value.
For example, The ID 40001 is ID for the condition descriptor card condition. The ID 400012 is the ID for the Very Good card condition value.",
- "items": {
- "$ref": "#/components/schemas/ItemConditionDescriptorValue"
+ "/marketplace/{marketplace_id}/get_product_safety_labels": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns product safety label information for the specified eBay marketplace. The information includes IDs, descriptions, and URLs (as applicable) for the available statements and pictograms. The returned statements are localized for the default language of the marketplace. If a marketplace does not support product safety label information, no response payload is returned, but only a 204 No content status code.This information is used by the seller to add product safety label related information to their listings. The getRegulatoryPolicies method can be used to see which categories recommend or require product safety labels.
",
+ "operationId": "getProductSafetyLabels",
+ "parameters": [
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values. See the following note for exceptions.Note: This method is not supported in the EBAY_HK, EBAY_MY, EBAY_TW, or EBAY_PH marketplaces.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ProductSafetyLabelsResponse"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "description": "This type is used to display the possible condition descriptors and condition values applicable for a specified category. It also returns usage requirements, maximum length, cardinality, and help text."
- },
- "ItemConditionDescriptorConstraint": {
- "type": "object",
- "properties": {
- "applicableToConditionDescriptorIds": {
- "type": "array",
- "description": "This array is returned if the corresponding condition descriptor requires that one or more other associated condition descriptors must also be specified in a listing. The condition descriptor IDs for the associated condition descriptors are returned here.
For example, the Grade and Grader condition descriptors must always be specified together in a listing for Graded cards.",
- "items": {
- "type": "string"
+ "/marketplace/{marketplace_id}/get_regulatory_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns regulatory policies for one, multiple, or all eBay categories in an eBay marketplace. The identifier of the eBay marketplace is passed in as a path parameter, and unless one or more eBay category IDs are passed in through the filter query parameter, this method will return metadata for every listing category in the specified marketplace.Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.
",
+ "operationId": "getRegulatoryPolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "A query parameter that can be used to limit the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree that should be returned.
Pass in the categoryId values using a URL-encoded, pipe-separated ('|') list. For example:
filter=categoryIds%3A%7B100%7C101%7C102%7D
Maximum: 50",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information shall be retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.Note: This method is not supported in the EBAY_HK, EBAY_MY, EBAY_TW, or EBAY_PH marketplaces.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RegulatoryPolicyResponse"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ },
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46005": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only {maxCategoryIdsAllowed} Category IDs are allowed in the 'filter' parameter."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- },
- "cardinality": {
- "type": "string",
- "description": "The value returned in this field indicates whether a condition descriptor can have a single value or multiple values. For implementation help, refer to eBay API documentation"
- },
- "defaultConditionDescriptorValueId": {
- "type": "string",
- "description": "The default condition descriptor value that will be set if there are multiple values."
- },
- "maxLength": {
- "type": "integer",
- "description": "The maximum characters allowed for a condition descriptor. This field is only returned/applicable for condition descriptors that allow free text for condition descriptor values. ",
- "format": "int32"
- },
- "mode": {
- "type": "string",
- "description": "The value returned in this field indicates whether the supported values for a condition descriptor are predefined or if the seller manually specified the value.
Note: FREE_TEXT is currently only applicable to the Certification Number condition descriptor. For implementation help, refer to eBay API documentation"
- },
- "usage": {
- "type": "string",
- "description": "This value indicates whether or not the condition descriptor is required for the item condition. Currently, this field is only returned if the condition descriptor is required for the item condition. For implementation help, refer to eBay API documentation"
- }
},
- "description": "This type specifies the constraints on a condition descriptor, such as the maximum length, default condition descriptor value ID, cardinality, mode, usage, and applicable descriptor IDs."
- },
- "ItemConditionDescriptorValue": {
- "type": "object",
- "properties": {
- "conditionDescriptorValueAdditionalHelpText": {
- "type": "array",
- "description": "Additional information about the the condition of the item that is not included in the conditionDescriptorValueHelpText field.",
- "items": {
- "type": "string"
- }
- },
- "conditionDescriptorValueConstraints": {
- "type": "array",
- "description": "The constraints on a condition descriptor value, such as which descriptor value IDs and Descriptor ID it is associated with.",
- "items": {
- "$ref": "#/components/schemas/ItemConditionDescriptorValueConstraint"
+ "/marketplace/{marketplace_id}/get_return_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns the eBay policies that define whether or not you must include a return policy for the items you list in the categories of a specific marketplace, plus the guidelines for creating domestic and international return policies in the different eBay categories.
By default, this method returns the entire category tree for the specified marketplace. You can limit the size of the result set by using the filter query parameter to specify only the category IDs you want to review.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip.",
+ "operationId": "getReturnPolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned.
When you specify a categoryId value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{100|101|102}
Note that you must URL-encode the parameter list, which results in the following filter for the above example:
filter=categoryIds%3A%7B100%7C101%7C102%7D",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Encoding",
+ "in": "header",
+ "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.
For more information, refer to HTTP request headers.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ReturnPolicyResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only 50 Category IDs specified in the filter are considered."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- },
- "conditionDescriptorValueHelpText": {
- "type": "string",
- "description": "A detailed description of the condition descriptor value. "
- },
- "conditionDescriptorValueId": {
- "type": "string",
- "description": "The unique identification number of a condition descriptor value associated with the conditionDescriptorValueName."
- },
- "conditionDescriptorValueName": {
- "type": "string",
- "description": "The human-readable label for the condition descriptor value associated with the conditionDescriptorValueID."
- }
},
- "description": "This type displays the possible values for the corresponding condition descriptor, along with help text and constraint information."
- },
- "ItemConditionDescriptorValueConstraint": {
- "type": "object",
- "properties": {
- "applicableToConditionDescriptorId": {
- "type": "string",
- "description": "This string is returned if the corresponding condition descriptor value requires an associated condition descriptor that must also be specified in a listing. The condition descriptor ID for the associated condition descriptors is returned here."
- },
- "applicableToConditionDescriptorValueIds": {
- "type": "array",
- "description": "This array is returned if the corresponding condition descriptor value is required for one or more associated condition descriptor values that must also be specified in a listing. The condition descriptor values IDs for the associated condition descriptor values are returned here.",
- "items": {
- "type": "string"
+ "/marketplace/{marketplace_id}/get_shipping_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns eBay shipping policy metadata for all leaf categories on the specified marketplace.By default, this method returns metadata on all leaf categories. You can limit the size of the result set by using the filter query parameter to specify only the leaf category IDs you want to review.
If you specify a valid marketplace ID but that marketplace does not contain policy information, or if you filter out all results, a successful call returns a 204 No content status code with an empty response body.",
+ "operationId": "getShippingPolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This query parameter limits the response by only returning metadata for the specified leaf categories. Supply the categoryId for one or more leaf categories. You can verify if a category is a leaf category by using the Taxonomy API and looking for a \"leafCategory\": true tag.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{3767|171784}",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:
- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ShippingPoliciesResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only {maxCategoryIdsAllowed} Category IDs are allowed in the 'filter' parameter."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "description": "This type shows the constraints on a condition descriptor value, such as any associated condition descriptor ID and condition descriptor value IDs required for a listing."
- },
- "ItemConditionPolicy": {
- "type": "object",
- "properties": {
- "categoryId": {
- "type": "string",
- "description": "The category ID to which the item-condition policy applies."
- },
- "categoryTreeId": {
- "type": "string",
- "description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree.
A category tree is a hierarchical framework of eBay categories that begins at the root node of the tree and extends to include all the child nodes in the tree. Each child node in the tree is an eBay category that is represented by a unique categoryId value. Within a category tree, the root node has no parent node and leaf nodes are nodes that have no child nodes."
- },
- "itemConditionRequired": {
- "type": "boolean",
- "description": "This flag denotes whether or not you must list the item condition in a listing for the specified category. If set to true, you must specify an item condition for the associated category."
- },
- "itemConditions": {
- "type": "array",
- "description": "The item-condition values allowed in the category.
Note: The Ć¢ā¬ĖSeller RefurbishedĆ¢ā¬ā¢ item condition (condition ID 2500) has been replaced by the 'Excellent - Refurbished', 'Very Good - Refurbished', and 'Good - Refurbished' item conditions in a select number of eBay marketplaces and categories. See the eBay Refurbished Program - Category and marketplace support topic for more details.
Similar to the Ć¢ā¬ĖCertified RefurbishedĆ¢ā¬ā¢ item condition (condition ID 2000), a sellerĆ¢ā¬ā¢s OAuth user token will have to be used instead of an OAuth application token, since each seller must go through an application and qualification process before using any of these new refurbished item conditions in supported categories. If a seller is not qualified to use the new refurbished item conditions, these item condition values will not be returned by getItemConditionPolicies.",
- "items": {
- "$ref": "#/components/schemas/ItemCondition"
- }
- }
- }
- },
- "ItemConditionPolicyResponse": {
- "type": "object",
- "properties": {
- "itemConditionPolicies": {
- "type": "array",
- "description": "A list of category IDs and the policies for how to indicate an item's condition in each of the listed categories.",
- "items": {
- "$ref": "#/components/schemas/ItemConditionPolicy"
- }
- },
- "warnings": {
- "type": "array",
- "description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- },
- "ListingStructurePolicy": {
- "type": "object",
- "properties": {
- "categoryId": {
- "type": "string",
- "description": "The category ID to which the listing-structure policy applies."
- },
- "categoryTreeId": {
- "type": "string",
- "description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree.
A category tree is a hierarchical framework of eBay categories that begins at the root node of the tree and extends to include all the child nodes in the tree. Each child node in the tree is an eBay category that is represented by a unique categoryId value. Within a category tree, the root node has no parent node and leaf nodes are nodes that have no child nodes."
- },
- "variationsSupported": {
- "type": "boolean",
- "description": "This flag denotes whether or not the associated category supports listings with item variations. If set to true, the category does support item variations."
- }
- }
- },
- "ListingStructurePolicyResponse": {
- "type": "object",
- "properties": {
- "listingStructurePolicies": {
- "type": "array",
- "description": "Returns a list of category IDs plus a flag indicating whether or not each listed category supports item variations.",
- "items": {
- "$ref": "#/components/schemas/ListingStructurePolicy"
- }
- },
- "warnings": {
- "type": "array",
- "description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
- "items": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- },
- "NegotiatedPricePolicy": {
- "type": "object",
- "properties": {
- "bestOfferAutoAcceptEnabled": {
- "type": "boolean",
- "description": "This flag denotes whether or not the category supports the setting of a price at which best offers are automatically accepted. If set to true, the category does support the setting of an automatic price for best-offers."
- },
- "bestOfferAutoDeclineEnabled": {
- "type": "boolean",
- "description": "This flag denotes whether or not the category supports the setting of an auto-decline price for best offers. If set to true, the category does support the setting of an automatic-decline price for best-offers."
- },
- "bestOfferCounterEnabled": {
- "type": "boolean",
- "description": "This flag denotes whether or not the category supports the setting for an automatic counter-offer on best offers. If set to true, the category does support the setting of an automatic counter-offer price for best-offers."
- },
- "categoryId": {
- "type": "string",
- "description": "The category ID to which the negotiated-price policies apply."
- },
- "categoryTreeId": {
- "type": "string",
- "description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree.
A category tree is a hierarchical framework of eBay categories that begins at the root node of the tree and extends to include all the child nodes in the tree. Each child node in the tree is an eBay category that is represented by a unique categoryId value. Within a category tree, the root node has no parent node and leaf nodes are nodes that have no child nodes."
- }
- }
- },
- "NegotiatedPricePolicyResponse": {
- "type": "object",
- "properties": {
- "negotiatedPricePolicies": {
- "type": "array",
- "description": "A list of category IDs and the policies related to negotiated-price items for each of the listed categories.",
- "items": {
- "$ref": "#/components/schemas/NegotiatedPricePolicy"
+ "/marketplace/{marketplace_id}/get_site_visibility_policies": {
+ "get": {
+ "tags": [
+ "marketplace"
+ ],
+ "description": "This method returns eBay international site visibility policy metadata for all leaf categories on the specified marketplace.By default, this method returns metadata on all leaf categories. You can limit the size of the result set by using the filter query parameter to specify only the leaf category IDs you want to review.
If you specify a valid marketplace ID but that marketplace does not contain policy information, or if you filter out all results, a successful call returns a 204 No content status code with an empty response body.",
+ "operationId": "getSiteVisibilityPolicies",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "description": "This query parameter limits the response by only returning metadata for the specified leaf categories. Supply the categoryId for one or more leaf categories. You can verify if a category is a leaf category by using the Taxonomy API and looking for a \"leafCategory\": true tag.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example:filter=categoryIds:{3767|171784}",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:
- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SiteVisibilityPoliciesResponse"
+ }
+ }
+ },
+ "x-response-codes": {
+ "errors": {
+ "46002": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
+ },
+ "46003": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified categoryId was not found for the marketplace."
+ },
+ "46004": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Only {maxCategoryIdsAllowed} Category IDs are allowed in the 'filter' parameter."
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- },
- "warnings": {
- "type": "array",
- "description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
- "items": {
- "$ref": "#/components/schemas/Error"
+ },
+ "/compatibilities/get_compatibilities_by_specification": {
+ "post": {
+ "tags": [
+ "compatibilities"
+ ],
+ "description": "This method is used to retrieve all compatible application name-value pairs for a part based on the provided specification(s).
The part's relevant dimensions and/or characteristics can be provided through the specifications container. For example, when retrieving compatible application name-value pairs for a tire, the tire's dimensions (such as the section width or rim diameter) should be provided.
By default, all compatible application name-value pairs for the specifications are returned. You can limit the size of the result set by using the compatibilityPropertyFilters array to specify the properties (such as make, model, year, or trim) you wish to be included in the response.
Note: The getCompatibilityPropertyNames and getCompatibilityPropertyValues methods can be used to retrieve valid property names and values that can be used as the name-value pairs to define specifications.",
+ "operationId": "getCompatibilitiesBySpecification",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See Metadata API requirements and restrictions for supported values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client.
Its value should be set to application/json.
For more information, refer to HTTP request headers in the Using eBay RESTful APIs guide.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the properties and specifications to use to search for compatibilities.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the properties and specifications to use to search for compatibilities.",
+ "$ref": "#/components/schemas/SpecificationRequest"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SpecificationResponse"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "47000": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "Item compatibilities are not enabled for category ID {{category_id}} or invalid propertyFilter."
+ },
+ "47002": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The category {{category_id}} specified in the request does not support compatibilities."
+ },
+ "47003": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "A required field is missing from the request."
+ },
+ "47004": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "Invalid data supplied in the request."
+ },
+ "47005": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The marketplace id {{marketplaceId}} specified in the request is invalid."
+ },
+ "47006": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The marketplace id {{marketplaceId}} specified in the request does not support compatibility."
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Unauthorized"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
- }
- },
- "Pictogram": {
- "type": "object",
- "properties": {
- "pictogramId": {
- "type": "string",
- "description": "The identifier of the pictogram. For sample values, see Pictogram sample values."
- },
- "pictogramDescription": {
- "type": "string",
- "description": "The description of the pictogram localized to the default language of the marketplace. For sample values, see Pictogram sample values."
- },
- "pictogramUrl": {
- "type": "string",
- "description": "The URL of the pictogram."
- }
},
- "description": "A type that describes pictograms for hazardous materials labels."
- },
- "ReturnPolicy": {
- "type": "object",
- "properties": {
- "categoryId": {
- "type": "string",
- "description": "The category ID to which the return policies apply."
- },
- "categoryTreeId": {
- "type": "string",
- "description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree.
A category tree is a hierarchical framework of eBay categories that begins at the root node of the tree and extends to include all the child nodes in the tree. Each child node in the tree is an eBay category that is represented by a unique categoryId value. Within a category tree, the root node has no parent node and leaf nodes are nodes that have no child nodes."
- },
- "domestic": {
- "description": "This complex type defines the category policies related to domestic item returns.",
- "$ref": "#/components/schemas/ReturnPolicyDetails"
- },
- "international": {
- "description": "This complex type defines the category policies related to international item returns.",
- "$ref": "#/components/schemas/ReturnPolicyDetails"
- },
- "required": {
- "type": "boolean",
- "description": "If set to true, this flag indicates that you must specify a return policy for items listed in the associated category.
Note that not accepting returns (setting returnsAcceptedEnabled to false) is a valid return policy."
- }
- }
- },
- "ReturnPolicyDetails": {
- "type": "object",
- "properties": {
- "policyDescriptionEnabled": {
- "type": "boolean",
- "description": "If set to true, this flag indicates you can supply a detailed return policy description within your return policy (for example, by populating the returnInstructions field in the Account API's createReturnPolicy). User-supplied return policy details are allowed only in the DE, ES, FR, and IT marketplaces."
- },
- "refundMethods": {
- "type": "array",
- "description": "A list of refund methods allowed for the associated category.",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
+ "/compatibilities/get_compatibility_property_names": {
+ "post": {
+ "tags": [
+ "compatibilities"
+ ],
+ "description": "This method is used to retrieve product compatibility property names for the specified compatibility-enabled category.
Compatibility property names can be used alongside the corresponding compatibility property value (retrieved using the getCompatibilityPropertyValues method) to describe the assembly for which an item is compatible.
The categoryId of the compatibility-enabled category for which to retrieve compatibility property names is required in the request body.
By default, all property names within the compatibility category of the specified compatibility-enable category are returned. You can limit the size of the result set by using the dataset array to specify the types of properties you want returned.",
+ "operationId": "getCompatibilityPropertyNames",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See Metadata API requirements and restrictions for supported values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client.
Its value should be set to application/json.
For more information, refer to HTTP request headers in the Using eBay RESTful APIs guide.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the properties used to retrieve compatibility property names.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the properties used to retrieve compatibility property names.",
+ "$ref": "#/components/schemas/PropertyNamesRequest"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PropertyNamesResponse"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "47000": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "Item compatibilities are not enabled for category ID {{category_id}} or invalid propertyFilter."
+ },
+ "47001": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The category {{category_id}} specified in the request is not a valid eBay category for the marketplace."
+ },
+ "47002": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The category {{category_id}} specified in the request does not support compatibilities."
+ },
+ "47003": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "A required field is missing from the request."
+ },
+ "47004": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "Invalid data supplied in the request."
+ },
+ "47005": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The marketplace id {{marketplaceId}} specified in the request is invalid."
+ },
+ "47006": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The marketplace id {{marketplaceId}} specified in the request does not support compatibility."
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Unauthorized"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- },
- "returnMethods": {
- "type": "array",
- "description": "A list of return methods allowed for the associated category.",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
+ },
+ "/compatibilities/get_compatibility_property_values": {
+ "post": {
+ "tags": [
+ "compatibilities"
+ ],
+ "description": "This method is used to retrieve product compatibility property values associated with a single property name, in the specified category.
Compatibility property values can be used alongside the corresponding compatibility property name (retrieved using the getCompatibilityPropertyNames method) to describe the assembly for which an item is compatible.
The categoryId of the compatibility-enabled category for which to retrieve compatibility property values is required in the request body, as well as the propertyName for which you wish to retrieve associated values.
By default, all property values associated with the specified propertyName are returned. You can limit the size of the result set by using the propertyFilter array. Only property values associated with the specified name-value pairs will be returned.",
+ "operationId": "getCompatibilityPropertyValues",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See Metadata API requirements and restrictions for supported values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client.
Its value should be set to application/json.
For more information, refer to HTTP request headers in the Using eBay RESTful APIs guide.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the category ID and property name for which to retrieve values.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the category ID and property name for which to retrieve values.",
+ "$ref": "#/components/schemas/PropertyValuesRequest"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PropertyValuesResponse"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "47000": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "Item compatibilities are not enabled for category ID {{category_id}} or invalid propertyFilter."
+ },
+ "47002": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The category {{category_id}} specified in the request does not support compatibilities."
+ },
+ "47003": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "A required field is missing from the request."
+ },
+ "47004": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "Invalid data supplied in the request."
+ },
+ "47005": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The marketplace id {{marketplaceId}} specified in the request is invalid."
+ },
+ "47006": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The marketplace id {{marketplaceId}} specified in the request does not support compatibility."
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Unauthorized"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- },
- "returnPeriods": {
- "type": "array",
- "description": "A list of return periods allowed for the associated category.
Note that different APIs require you to enter the return period in different ways. For example, the Account API uses the complex TimeDuration type, which takes two values (a unit and a value), whereas the Trading API takes a single value (such as Days_30).",
- "items": {
- "$ref": "#/components/schemas/TimeDuration"
+ },
+ "/compatibilities/get_multi_compatibility_property_values": {
+ "post": {
+ "tags": [
+ "compatibilities"
+ ],
+ "description": "This method is used to retrieve product compatibility property values associated with multiple property names, in the specified category.
Compatibility property values can be used alongside the corresponding compatibility property name (retrieved using the getCompatibilityPropertyNames method) to describe the assembly for which an item is compatible.
The categoryId of the compatibility-enabled category for which to retrieve compatibility property values is required in the request body, as well as the propertyNames for which you wish to retrieve associated property values. The propertyFilter array is also required to constrain the output. Only property values associated with the specified name-value pairs will be returned.",
+ "operationId": "getMultiCompatibilityPropertyValues",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See Metadata API requirements and restrictions for supported values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client.
Its value should be set to application/json.
For more information, refer to HTTP request headers in the Using eBay RESTful APIs guide.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines the category ID and property names for which to retrieve values.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines the category ID and property names for which to retrieve values.",
+ "$ref": "#/components/schemas/MultiCompatibilityPropertyValuesRequest"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/MultiCompatibilityPropertyValuesResponse"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "47000": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "Item compatibilities are not enabled for category ID {{category_id}} or invalid propertyFilter."
+ },
+ "47002": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The category {{category_id}} specified in the request does not support compatibilities."
+ },
+ "47003": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "A required field is missing from the request."
+ },
+ "47004": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "Invalid data supplied in the request."
+ },
+ "47005": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The marketplace id {{marketplaceId}} specified in the request is invalid."
+ },
+ "47006": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The marketplace id {{marketplaceId}} specified in the request does not support compatibility."
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Unauthorized"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- },
- "returnsAcceptanceEnabled": {
- "type": "boolean",
- "description": "If set to true, this flag indicates the seller can configure how they handle domestic returns."
- },
- "returnShippingCostPayers": {
- "type": "array",
- "description": "A list of allowed values for who pays for the return shipping cost.
Note that for SNAD returns, the seller is always responsible for the return shipping cost.",
- "items": {
- "type": "string",
- "description": " For implementation help, refer to eBay API documentation"
+ },
+ "/compatibilities/get_product_compatibilities": {
+ "post": {
+ "tags": [
+ "compatibilities"
+ ],
+ "description": "This method is used to retrieve all available item compatibility details for the specified product.
Item compatibility details can be used to see the properties for which an item is compatible. For example, if you are searching for a part for a specific vehicle, you can use this method to see the years, engine, and/or trim for which the part is compatible. Item compatibility details are returned as name-value pairs.
The product for which to retrieve item compatibility details must be provided through the productIdentifier field. This value can be either an eBay specific identifier (such as an ePID) or an external identifier (such as a UPC).
By default, all available item compatibility details for the specified product are returned. You can limit the size of the result set using the dataset or datasetPropertyName fields to specify the types of properties you want returned in the response. The applicationPropertyFilter array can also be used so that only parts compatible with the specified name-value pairs are returned.",
+ "operationId": "getProductCompatibilities",
+ "parameters": [
+ {
+ "name": "X-EBAY-C-MARKETPLACE-ID",
+ "in": "header",
+ "description": "This header identifies the seller's eBay marketplace.
See Metadata API requirements and restrictions for supported values.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client.
Its value should be set to application/json.
For more information, refer to HTTP request headers in the Using eBay RESTful APIs guide.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This type defines properties for which to find compatibilities.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This type defines properties for which to find compatibilities.",
+ "$ref": "#/components/schemas/ProductRequest"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ProductResponse"
+ }
+ }
+ }
+ },
+ "204": {
+ "description": "No Content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "47000": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "Item compatibilities are not enabled for category ID {{category_id}} or invalid propertyFilter."
+ },
+ "47003": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "A required field is missing from the request."
+ },
+ "47004": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "Invalid data supplied in the request."
+ },
+ "47005": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The marketplace id {{marketplaceId}} specified in the request is invalid."
+ },
+ "47006": {
+ "domain": "API",
+ "category": "REQUEST",
+ "description": "The marketplace id {{marketplaceId}} specified in the request does not support compatibility."
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Unauthorized"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "description": "This container defines the category policies that relate to domestic and international return policies (the return shipping is made via a domestic or an international shipping service, respectively)."
- },
- "ReturnPolicyResponse": {
- "type": "object",
- "properties": {
- "returnPolicies": {
- "type": "array",
- "description": "A list of elements, where each contains a category ID and a flag that indicates whether or not listings in that category require a return policy.",
- "items": {
- "$ref": "#/components/schemas/ReturnPolicy"
+ "/shipping/marketplace/{marketplace_id}/get_exclude_shipping_locations": {
+ "get": {
+ "tags": [
+ "shipping:marketplace"
+ ],
+ "description": "This method retrieves a list of locations that the seller can use as excluded shipping locations within their listings or in their fulfillment business policies for the specified marketplace. These are locations that a seller designates as areas where they will not ship items. Excluded shipping locations and ship-to locations are used in tandem at the listing level and in fulfillment business policies. Excluded shipping locations and ship-to locations share a lot of the same values and they should not contradict each other.
Manage excluded shipping locations using business policies through the fulfillment_policy resource of the Account v1 API.
",
+ "operationId": "getExcludeShippingLocations",
+ "parameters": [
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which excluded shipping locations information is retrieved.
See MarketplaceIdEnum for supported eBay marketplace ID values. Note: When listing the items on the French Canada, French Belgium, and Dutch Belgium marketplaces, also set the Accept-Language header as needed.
",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ShippingExcludeLocationResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- },
- "warnings": {
- "type": "array",
- "description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
- "items": {
- "$ref": "#/components/schemas/Error"
+ },
+ "/shipping/marketplace/{marketplace_id}/get_handling_times": {
+ "get": {
+ "tags": [
+ "shipping:marketplace"
+ ],
+ "description": "This method retrieves a list of supported handling times for the specified marketplace. The handling time returned specifies the maximum number of business days the eBay site allows for shipping an item to domestic buyers after receiving a cleared payment. Handling times apply to both domestic and international orders. If the handling time is 1 day, the seller commits to dropping the item off for shipment one business day after payment clears. Manage handing times using business policies through the fulfillment_policy resource of the Account v1 API.
",
+ "operationId": "getHandlingTimes",
+ "parameters": [
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which handling times information is retrieved.
See MarketplaceIdEnum for supported eBay marketplace ID values. Note: When listing the items on the French Canada, French Belgium, and Dutch Belgium marketplaces, also set the Accept-Language header as needed.
",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ShippingHandlingTimeResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
- }
- },
- "SalesTaxJurisdiction": {
- "type": "object",
- "properties": {
- "salesTaxJurisdictionId": {
- "type": "string",
- "description": "The unique ID for a sales-tax jurisdiction.
Important! When countryCode is set to US, IDs for all 50 states, Washington, DC, and all US territories will be returned. However, the only salesTaxJurisdictionId values currently supported are:
AS (American Samoa)GU (GuamMP Northern Mariana IslandsPW (Palau)VI (US Virgin Islands)
The value returned in the shippingCarrier field is the enumerated value required when providing shipment tracking information for that carrier.
Tip: Use the getShippingServices method to explore available shipping services for each carrier.
Manage shipping carriers using business policies through the fulfillment_policy resource of the Account v1 API.
",
+ "operationId": "getShippingCarriers",
+ "parameters": [
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which shipping carriers information is retrieved.
See MarketplaceIdEnum for supported eBay marketplace ID values. Note: When listing the items on the French Canada, French Belgium, and Dutch Belgium marketplaces, also set the Accept-Language header as needed.
",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ShippingCarrierResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
}
- }
},
- "description": "This complex type contains a list of sales-tax jurisdictions."
- },
- "SignalWord": {
- "type": "object",
- "properties": {
- "signalWordId": {
- "type": "string",
- "description": "The identifier of the signal word. For more information, see Signal word information."
- },
- "signalWordDescription": {
- "type": "string",
- "description": "The description of the signal word localized to the default language of the marketplace. For more information, see Signal word information."
- }
+ "/shipping/marketplace/{marketplace_id}/get_shipping_locations": {
+ "get": {
+ "tags": [
+ "shipping:marketplace"
+ ],
+ "description": "This method retrieves a list of supported shipping locations for the specified marketplace. It provides sellers with information on where they can ship their items. Sellers can use this information to configure their shipping settings. Tip: Use the getExcludeShippingLocations method to return locations where the seller does not ship.
Manage shipping locations using business policies through the fulfillment_policy resource of the Account v1 API.
",
+ "operationId": "getShippingLocations",
+ "parameters": [
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which shipping locations information is retrieved.
See MarketplaceIdEnum for supported eBay marketplace ID values. Note: When listing the items on the French Canada, French Belgium, and Dutch Belgium marketplaces, also set the Accept-Language header as needed.
",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ShippingLocationResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
+ }
},
- "description": "A type that describes signal words for hazardous materials labels."
- },
- "TimeDuration": {
- "type": "object",
- "properties": {
- "unit": {
- "type": "string",
- "description": "A time-measurement unit that specifies a singular period of time.
A span of time is defined when you apply the value specified in the value field to the value specified for unit.
Time-measurement units can be YEAR, MONTH, DAY, and so on. See TimeDurationUnitEnum for a complete list of possible time-measurement units. For implementation help, refer to eBay API documentation"
- },
- "value": {
- "type": "integer",
- "description": "An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.",
- "format": "int32"
- }
+ "/shipping/marketplace/{marketplace_id}/get_shipping_services": {
+ "get": {
+ "tags": [
+ "shipping:marketplace"
+ ],
+ "description": "This method retrieves a list of shipping services supported for the specified marketplace, including valid shipping services, shipping times, and package constraints such as size and weight.Manage shipping services using business policies through the fulfillment_policy resource of the Account v1 API.
",
+ "operationId": "getShippingServices",
+ "parameters": [
+ {
+ "name": "Accept-Language",
+ "in": "header",
+ "description": "This header is required to retrieve metadata for the French Canada, French Belgium, and Dutch Belgium marketplaces.
Follow the instructions below to retrieve metadata for these three marketplaces:- French Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of fr-BE. - Dutch Belgium: Set the marketplace_id path parameter value to
EBAY_BE, and include the Accept-Language header with a value of nl-BE. - French Canada: Set the marketplace_id path parameter value to
EBAY_CA, and include the Accept-Language header with a value of fr-CA.
Note: If EBAY_CA is set as the marketplace_id path parameter and the Accept-Language header is not used, the marketplace will default to the English Canada marketplace.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "marketplace_id",
+ "in": "path",
+ "description": "This path parameter specifies the eBay marketplace for which shipping services information is retrieved.
See MarketplaceIdEnum for supported eBay marketplace ID values. Note: When listing the items on the French Canada, French Belgium, and Dutch Belgium marketplaces, also set the Accept-Language header as needed.
",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ShippingServiceResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "46001": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "The specified marketplace ID was not found."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "46000": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
+ }
},
- "description": "A complex type that specifies a period of time using a specified time-measurement unit."
- }
+ "/country/{countryCode}/sales_tax_jurisdiction": {
+ "get": {
+ "tags": [
+ "country"
+ ],
+ "description": "This method retrieves all sales-tax jurisdictions for the country specified in the countryCode path parameter. Countries with valid sales-tax jurisdictions are Canada and the US.
The response from this call tells you the jurisdictions for which a seller can configure tax tables. Although setting up tax tables is optional, you can use the createOrReplaceSalesTax method in the Account API call to configure the tax tables for the jurisdictions into which you sell.
Note: Sales-tax tables are only available for the US (EBAY_US) and Canada (EBAY_CA) marketplaces.
Important! In the US, eBay now calculates, collects, and remits sales tax to the proper taxing authorities in all 50 states and Washington, DC. Sellers can no longer specify sales-tax rates for these jurisdictions using a tax table.
However, sellers may continue to use a sales-tax table to set rates for the following US territories:
- American Samoa (AS)
- Guam (GU)
- Northern Mariana Islands (MP)
- Palau (PW)
- US Virgin Islands (VI)
For additional information, refer to
Taxes and import charges.
Note: Sales-tax tables are available only for the US and Canada marketplaces. Therefore, the only supported values are:",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SalesTaxJurisdictions"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "45400": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Invalid input. {additionalInfo}"
+ },
+ "45401": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Invalid {fieldName}."
+ },
+ "45402": {
+ "domain": "API_METADATA",
+ "category": "REQUEST",
+ "description": "Tax table not supported for {fieldName}."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not Found"
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "45500": {
+ "domain": "API_METADATA",
+ "category": "APPLICATION",
+ "description": "System error."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope"
+ ]
+ }
+ ]
+ }
+ }
},
- "securitySchemes": {
- "api_auth": {
- "type": "oauth2",
- "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
- "flows": {
- "clientCredentials": {
- "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
- "scopes": {
- "https://api.ebay.com/oauth/api_scope": "View public data from eBay"
+ "components": {
+ "schemas": {
+ "Amount": {
+ "type": "object",
+ "properties": {
+ "currency": {
+ "type": "string",
+ "description": "The three-letter ISO 4217 code representing the currency of the amount in the value field.
Restriction: Only the currency of the marketplace is supported. For example, on the US marketplace the only currency supported is USD. For implementation help, refer to eBay API documentation"
+ },
+ "value": {
+ "type": "string",
+ "description": "The monetary amount, in the currency specified by the currency field."
+ }
+ },
+ "description": "The type that defines the fields for the currency and a monetary amount."
+ },
+ "AutomotivePartsCompatibilityPolicy": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The category ID to which the automotive parts compatibility policies apply."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree.
A category tree is a hierarchical framework of eBay categories that begins at the root node of the tree and extends to include all the child nodes in the tree. Each child node in the tree is an eBay category that is represented by a unique categoryId value. Within a category tree, the root node has no parent node and leaf nodes are nodes that have no child nodes."
+ },
+ "compatibilityBasedOn": {
+ "type": "string",
+ "description": "Indicates whether the category supports parts compatibility by either ASSEMBLY or by SPECIFICATION. For implementation help, refer to eBay API documentation"
+ },
+ "compatibleVehicleTypes": {
+ "type": "array",
+ "description": "Indicates the compatibility classification of the part based on high-level vehicle types.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "maxNumberOfCompatibleVehicles": {
+ "type": "integer",
+ "description": "Specifies the maximum number of compatible vehicle-applications allowed per item.",
+ "format": "int32"
+ }
+ }
+ },
+ "AutomotivePartsCompatibilityPolicyResponse": {
+ "type": "object",
+ "properties": {
+ "automotivePartsCompatibilityPolicies": {
+ "type": "array",
+ "description": "A list of category IDs and the automotive parts compatibility policies for each of the listed categories.",
+ "items": {
+ "$ref": "#/components/schemas/AutomotivePartsCompatibilityPolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "CategoryPolicy": {
+ "type": "object",
+ "properties": {
+ "autoPayEnabled": {
+ "type": "boolean",
+ "description": "If this field is returned as true, the corresponding category supports immediate payment for listings. The immediate payment feature is applicable to fixed-price listings, to auction listings with the 'Buy It Now' option enabled, and for a motor vehicle listing that requires an initial deposit. If the immediate payment feature is enabled for a listing, the buyer must pay immediately after clicking the 'Buy it Now' button. This field is only returned when true (not returned when false).
"
+ },
+ "b2bVatEnabled": {
+ "type": "boolean",
+ "description": "If this field is returned as true, the corresponding category supports business-to-business (B2B) VAT listings. If this field is not present, the category does not have B2B VAT listings. This feature is applicable to the eBay Germany (DE), Austria (AT), and Switzerland (CH) sites only.This field is only returned when true (not returned when false).
"
+ },
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay leaf category for which metadata is being returned."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "The unique identifier of the category tree."
+ },
+ "eanSupport": {
+ "type": "string",
+ "description": "This enumerated value indicates whether or not European Article Numbers (EANs) are supported/required when listing products in the category. For implementation help, refer to eBay API documentation"
+ },
+ "expired": {
+ "type": "boolean",
+ "description": "If this field is returned as true, the corresponding category is no longer a valid eBay category on the site, and items may not be listed in this category. You can use the getExpiredCategories method (of the Taxonomy API) to find the leaf category that replaced the expired category. This field is only returned when true (not returned when false).
"
+ },
+ "intangibleEnabled": {
+ "type": "boolean",
+ "description": "If this field is returned as true, the category supports the listing of intangible goods or services."
+ },
+ "isbnSupport": {
+ "type": "string",
+ "description": "This enumerated value indicates whether or not International Standard Book Numbers (ISBNs) are supported/required when listing products in the specified category. For implementation help, refer to eBay API documentation"
+ },
+ "lsd": {
+ "type": "boolean",
+ "description": "If this field (Lot Size Disabled) is returned as true, the corresponding category does not support lot listings. A lot listing is a listing that features multiple related items that must be purchased by one buyer in one transaction. This field is only returned when true (not returned when false).
"
+ },
+ "minimumReservePrice": {
+ "type": "number",
+ "description": "Indicates the Minimum Reserve Price for an auction listing in this category. If there is no Minimum Reserve Price, a value of 0.0 is returned in this field."
+ },
+ "orpa": {
+ "type": "boolean",
+ "description": "This field (Override Reserve Price Allowed) is returned as true if the eBay marketplace's default policy is to allow reserve prices for auction listings, but the corresponding category does not allow a reserve price. Note: This field is not returned if the marketplace does not permit reserve prices.
"
+ },
+ "orra": {
+ "type": "boolean",
+ "description": "If this field (Override Reduce Reserve Allowed) is returned as true, the seller can reduce or remove a reserve price that had already been reduced for an active auction listing."
+ },
+ "paymentMethods": {
+ "type": "array",
+ "description": "An array that indicates the acceptable offline payment methods that can be used when listing an item for sale in the corresponding category.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "reduceReserveAllowed": {
+ "type": "boolean",
+ "description": "If this field (Reduce Reserve Allowed) is true, the corresponding leaf category allows the seller to reduce an item's reserve price. If false, this field is not returned in the response and the corresponding leaf category on the site do not normally allow sellers to reduce an item's reserve price.This field is only returned when true (not returned when false).
"
+ },
+ "reservePriceAllowed": {
+ "type": "boolean",
+ "description": "This field indicates whether reserve prices are allowed for auction listings in this category. This field returns as true when the category supports reserve prices, or false if the eBay marketplace does not permit reserve prices or the category override blocks reserve prices (orpa is true)."
+ },
+ "upcSupport": {
+ "type": "string",
+ "description": "This enumerated value indicates whether or not the category on the specified eBay site supports the use of Universal Product Codes (UPCs) to help create a listing. For implementation help, refer to eBay API documentation"
+ },
+ "valueCategory": {
+ "type": "boolean",
+ "description": "When returned as true, this boolean indicates that the leaf category for the specified site is designated by eBay as a value category. Value categories can be used as a secondary category for a listing at no extra charge."
+ },
+ "virtual": {
+ "type": "boolean",
+ "description": "If this field is returned as true, the corresponding category is an eBay virtual category, a category in which items may not be listed.This field is only returned when true (not returned when false).
"
+ }
+ },
+ "description": "This type contains applicable policy metadata for the leaf categories returned for the marketplace."
+ },
+ "CategoryPolicyResponse": {
+ "type": "object",
+ "properties": {
+ "categoryPolicies": {
+ "type": "array",
+ "description": "This array contains applicable policy metadata for the leaf categories returned for the marketplace specified in the path parameter marketplace_id and optionally limited by only those leaf category IDs specified in the query parameter filter.",
+ "items": {
+ "$ref": "#/components/schemas/CategoryPolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "An array of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type contains applicable policy metadata for the leaf categories returned for the marketplace."
+ },
+ "ClassifiedAdPolicy": {
+ "type": "object",
+ "properties": {
+ "adFormatEnabled": {
+ "type": "string",
+ "description": "This enumerated value indicates the type or status of available Classified Ad formats for this category. For implementation help, refer to eBay API documentation"
+ },
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay leaf category for which metadata is being returned."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "The unique identifier of the category tree."
+ },
+ "classifiedAdAutoAcceptEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether the category supports the Best Offer Automatic Accept feature for Classified Ad listings."
+ },
+ "classifiedAdAutoDeclineEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether the category supports the Best Offer Automatic Reject feature for Classified Ad listings."
+ },
+ "classifiedAdBestOfferEnabled": {
+ "type": "string",
+ "description": "This enumerated value indicates if Best Offer is enabled, disabled, or required for Classified Ad listings in this category. For implementation help, refer to eBay API documentation"
+ },
+ "classifiedAdCompanyNameEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether this category supports including a company name in the seller's contact information. This element is for For Sale By Owner listings. "
+ },
+ "classifiedAdContactByAddressEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether this category supports including an address in the seller's contact information. This element is for For Sale By Owner listings. "
+ },
+ "classifiedAdContactByEmailEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether most categories support including an email address in the seller's contact information."
+ },
+ "classifiedAdContactByPhoneEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether most categories support including a phone number in the seller's contact information."
+ },
+ "classifiedAdCounterOfferEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether counter offers are allowed on Best offers for the category."
+ },
+ "classifiedAdPaymentMethodEnabled": {
+ "type": "string",
+ "description": "This enumerated value indicates support for the payment method being displayed to the user for the category. Even if enabled, checkout may or may not be enabled. For implementation help, refer to eBay API documentation"
+ },
+ "classifiedAdPhoneCount": {
+ "type": "integer",
+ "description": "Indicates how many contact phone numbers can be specified in contact information for the category. This element is for For Sale By Owner listings.",
+ "format": "int32"
+ },
+ "classifiedAdShippingMethodEnabled": {
+ "type": "boolean",
+ "description": "Indicates if shipping methods can be specified and displayed in the View Item page for the category."
+ },
+ "classifiedAdStreetCount": {
+ "type": "integer",
+ "description": "Indicates how many street addresses can be specified in contact information for the category. This element is for For Sale By Owner listings.",
+ "format": "int32"
+ },
+ "sellerContactDetailsEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether this category supports seller-level contact information for Classified Ad listings."
+ }
+ },
+ "description": "This type provides fields that contains applicable Classified Ad policy metadata for the leaf categories returned for the marketplace."
+ },
+ "ClassifiedAdPolicyResponse": {
+ "type": "object",
+ "properties": {
+ "classifiedAdPolicies": {
+ "type": "array",
+ "description": "This array contains applicable policy metadata for the leaf categories returned for the marketplace specified in the path parameter marketplace_id and optionally limited by only those leaf category IDs specified in the query parameter filter.",
+ "items": {
+ "$ref": "#/components/schemas/ClassifiedAdPolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "An array of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type contains applicable policy metadata for the leaf categories returned for the marketplace."
+ },
+ "Compatibility": {
+ "type": "object",
+ "properties": {
+ "compatibilityDetails": {
+ "type": "array",
+ "description": "This array returns a list of compatibility details associated with the specified property name(s).",
+ "items": {
+ "$ref": "#/components/schemas/CompatibilityDetails"
+ }
+ }
+ },
+ "description": "This type defines the property names and values that are compatible with the property name values specified in the request."
+ },
+ "CompatibilityDetails": {
+ "type": "object",
+ "properties": {
+ "propertyName": {
+ "type": "string",
+ "description": "The name of the property being described."
+ },
+ "propertyValue": {
+ "type": "string",
+ "description": "The value for the property specified in the propertyName field."
+ }
+ },
+ "description": "This type defines the compatible property names and values associated with the product."
+ },
+ "Currency": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "string",
+ "description": "The three-letter ISO 4217 code returned.
Restriction: Only the currency of the marketplace is supported. Examples: on the US marketplace, the only currency supported is the United States dollar, USD; on the Canadian marketplace, the only currency supported is the Canadian dollar, CAD. For implementation help, refer to eBay API documentation"
+ },
+ "description": {
+ "type": "string",
+ "description": "The description of the returned three-letter code. For example, if the code is USD, the description returned would be US Dollar."
+ }
+ },
+ "description": "The type defining valid currencies for the marketplace."
+ },
+ "DisabledProductFilter": {
+ "type": "object",
+ "properties": {
+ "excludeForEbayReviews": {
+ "type": "boolean",
+ "description": "Specifies whether to filter out products excluded for eBay reviews.
If set to true, items excluded from eBay reviews are not returned."
+ },
+ "excludeForEbaySelling": {
+ "type": "boolean",
+ "description": "Specifies whether to filter out products excluded for eBay selling.
If set to true, items excluded from eBay selling are not returned."
+ }
+ },
+ "description": "This type defines the booleans used to determine if a product is excluded from eBay selling and/or review."
+ },
+ "Error": {
+ "type": "object",
+ "properties": {
+ "category": {
+ "type": "string",
+ "description": "The category type for this error or warning. It takes an ErrorCategory object which can have one of three values:Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as \"Seller does not ship item to Antarctica\" or \"Buyer ineligible to purchase an alcoholic item\". Business errors are not syntactical input errors.Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.
"
+ },
+ "domain": {
+ "type": "string",
+ "description": "Name of the domain containing the service or application."
+ },
+ "errorId": {
+ "type": "integer",
+ "description": "A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.",
+ "format": "int32"
+ },
+ "inputRefIds": {
+ "type": "array",
+ "description": "Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "longMessage": {
+ "type": "string",
+ "description": "An expanded version of message that should be around 100-200 characters long, but is not required to be such."
+ },
+ "message": {
+ "type": "string",
+ "description": "An end user and app developer friendly device agnostic message. It explains what the error or warning is, and how to fix it (in a general sense). Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale."
+ },
+ "outputRefIds": {
+ "type": "array",
+ "description": "Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "parameters": {
+ "type": "array",
+ "description": "This optional complex field type contains a list of one or more context-specific ErrorParameter objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.",
+ "items": {
+ "$ref": "#/components/schemas/ErrorParameter"
+ }
+ },
+ "subdomain": {
+ "type": "string",
+ "description": "Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain."
+ }
+ },
+ "description": "A container that defines the elements of error and warning messages."
+ },
+ "ErrorParameter": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "Name of the entity that threw the error."
+ },
+ "value": {
+ "type": "string",
+ "description": "A description of the error."
+ }
+ },
+ "description": "Container for an error parameter."
+ },
+ "ExtendedProducerResponsibility": {
+ "type": "object",
+ "properties": {
+ "enabledForVariations": {
+ "type": "boolean",
+ "description": "An indication of whether the attribute can be enabled for listing variations.
If the value is true, the attribute may be specified at the variation level."
+ },
+ "name": {
+ "type": "string",
+ "description": "The name of the attribute included in the policy. For implementation help, refer to eBay API documentation"
+ },
+ "usage": {
+ "type": "string",
+ "description": "The usage guidelines for the attribute, in the specified marketplace. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A type that defines the attributes of an Extended Producer Responsibility policy."
+ },
+ "ExtendedProducerResponsibilityPolicy": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier for the category under which the policy applies."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "The unique identifier for the category tree under which the policy applies."
+ },
+ "supportedAttributes": {
+ "type": "array",
+ "description": "The details regarding the attributes included in the policy, such as their usage guidelines and whether they can be specified at the listing variation level.",
+ "items": {
+ "$ref": "#/components/schemas/ExtendedProducerResponsibility"
+ }
+ }
+ },
+ "description": "A type that defines the Extended Producer Responsibility policy."
+ },
+ "ExtendedProducerResponsibilityPolicyResponse": {
+ "type": "object",
+ "properties": {
+ "extendedProducerResponsibilities": {
+ "type": "array",
+ "description": "An array of response fields detailing the Extended Producer Responsibility policies supported for the specified marketplace.",
+ "items": {
+ "$ref": "#/components/schemas/ExtendedProducerResponsibilityPolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "A collection of warnings generated for the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "A type that defines the response fields for the getExtendedProducerResponsibilityPolicies method."
+ },
+ "GetCurrenciesResponse": {
+ "type": "object",
+ "properties": {
+ "defaultCurrency": {
+ "description": "This field specifies the default currency used by the marketplace.",
+ "$ref": "#/components/schemas/Currency"
+ },
+ "marketplaceId": {
+ "type": "string",
+ "description": "The ID of the eBay marketplace to which the default currency applies. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type defines the response fields specifying the default currency for the marketplace."
+ },
+ "HazardStatement": {
+ "type": "object",
+ "properties": {
+ "statementId": {
+ "type": "string",
+ "description": "The identifier of the statement. For sample values, see Hazard statement sample values."
+ },
+ "statementDescription": {
+ "type": "string",
+ "description": "The description of the statement localized to the default language of the marketplace. For sample values, see Hazard statement sample values."
+ }
+ },
+ "description": "A type that describes hazard statements for hazardous materials labels"
+ },
+ "HazardousMaterialDetailsResponse": {
+ "type": "object",
+ "properties": {
+ "signalWords": {
+ "type": "array",
+ "description": "This array contains available hazardous materials signal words for the specified marketplace.",
+ "items": {
+ "$ref": "#/components/schemas/SignalWord"
+ }
+ },
+ "statements": {
+ "type": "array",
+ "description": "This array contains available hazardous materials hazard statements for the specified marketplace.",
+ "items": {
+ "$ref": "#/components/schemas/HazardStatement"
+ }
+ },
+ "pictograms": {
+ "type": "array",
+ "description": "This array contains available hazardous materials hazard pictograms for the specified marketplace.",
+ "items": {
+ "$ref": "#/components/schemas/Pictogram"
+ }
+ }
+ },
+ "description": "A type that defines the response fields for the getHazardousMaterialsLabels method."
+ },
+ "ItemCondition": {
+ "type": "object",
+ "properties": {
+ "conditionDescription": {
+ "type": "string",
+ "description": "The human-readable label for the condition (e.g., \"New\"). This value is typically localized for each site.
Note that the display name can vary by category. For example, the description for condition ID 1000 could be called \"New: with Tags\" in one category and \"Brand New\" in another. For details on condition IDs and descriptions, see Item condition ID and name values."
+ },
+ "conditionDescriptors": {
+ "type": "array",
+ "description": "This array contains the possible condition descriptors and condition descriptor values applicable for the specified category. It also returns usage requirements, maximum length, cardinality, and help text.
Note: This array is only returned for categories that support condition descriptors.",
+ "items": {
+ "$ref": "#/components/schemas/ItemConditionDescriptor"
+ }
+ },
+ "conditionHelpText": {
+ "type": "string",
+ "description": "A detailed description of the condition denoted by the conditionID and conditionDescription. "
+ },
+ "conditionId": {
+ "type": "string",
+ "description": "The ID value of the selected item condition. For information on the supported condition ID values, see Item condition ID and name values."
+ },
+ "usage": {
+ "type": "string",
+ "description": "The value returned in this field indicates if there are any usage restrictions or requirements for the corresponding item condition in the corresponding category.
Note: Currently, the only supported value is 'RESTRICTED', and this field will only be returned for the following conditions: 2000, 2010, 2020, 2030. Sellers must be pre-approved to use any of these item conditions. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "Note: In all eBay marketplaces, Condition ID 2000 now maps to an item condition of 'Certified Refurbished', and not 'Manufacturer Refurbished'. To list an item as 'Certified Refurbished', a seller must be pre-qualified by eBay for this feature. Any seller who is not eligible for this feature will be blocked if they try to create a new listing or revise an existing listing with this item condition. Any active listings on any eBay marketplace that had 'Manufacturer Refurbished' as the item condition should have been automatically updated by eBay to the 'Seller Refurbished' item condition (Condition ID 2500).
Any seller that is interested in eligibility requirements to list with 'Certified Refurbished' should see the Certified refurbished program page in Seller Center. "
+ },
+ "ItemConditionDescriptor": {
+ "type": "object",
+ "properties": {
+ "conditionDescriptorConstraint": {
+ "description": "This container shows the constraints on a condition descriptor, such as the maximum length, default condition descriptor value ID, cardinality, mode, usage, and applicable descriptor IDs.",
+ "$ref": "#/components/schemas/ItemConditionDescriptorConstraint"
+ },
+ "conditionDescriptorHelpText": {
+ "type": "string",
+ "description": "A description of the condition descriptor that directs a user to its condition descriptor values.
For example, the help text for Card Condition is Select ungraded condition."
+ },
+ "conditionDescriptorId": {
+ "type": "string",
+ "description": "The unique identification number of a condition descriptor associated with with a conditionDescriptorName.
For example, 40001 is the ID for Card Condition.
These IDs are used in the addItem family of calls of the Trading API to provide condition descriptor names for the item. These IDs are used by the inventoryItem family of calls of the Inventory API to provide condition descriptor names for the item."
+ },
+ "conditionDescriptorName": {
+ "type": "string",
+ "description": "The human-readable label for the condition descriptor associated with the conditionDescriptorID.
For example, Card Condition is the condition descriptor name for ID 40001"
+ },
+ "conditionDescriptorValues": {
+ "type": "array",
+ "description": "This array shows the possible values that map to the corresponding conditionDescriptorName values. Constraint information and help text are also shown for each value.
For example, The ID 40001 is ID for the condition descriptor card condition. The ID 400012 is the ID for the Very Good card condition value.",
+ "items": {
+ "$ref": "#/components/schemas/ItemConditionDescriptorValue"
+ }
+ }
+ },
+ "description": "This type is used to display the possible condition descriptors and condition values applicable for a specified category. It also returns usage requirements, maximum length, cardinality, and help text."
+ },
+ "ItemConditionDescriptorConstraint": {
+ "type": "object",
+ "properties": {
+ "applicableToConditionDescriptorIds": {
+ "type": "array",
+ "description": "This array is returned if the corresponding condition descriptor requires that one or more other associated condition descriptors must also be specified in a listing. The condition descriptor IDs for the associated condition descriptors are returned here.
For example, the Grade and Grader condition descriptors must always be specified together in a listing for Graded cards.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "cardinality": {
+ "type": "string",
+ "description": "The value returned in this field indicates whether a condition descriptor can have a single value or multiple values. For implementation help, refer to eBay API documentation"
+ },
+ "defaultConditionDescriptorValueId": {
+ "type": "string",
+ "description": "The default condition descriptor value that will be set if there are multiple values."
+ },
+ "maxLength": {
+ "type": "integer",
+ "description": "The maximum characters allowed for a condition descriptor. This field is only returned/applicable for condition descriptors that allow free text for condition descriptor values. ",
+ "format": "int32"
+ },
+ "mode": {
+ "type": "string",
+ "description": "The value returned in this field indicates whether the supported values for a condition descriptor are predefined or if the seller manually specified the value.
Note: FREE_TEXT is currently only applicable to the Certification Number condition descriptor. For implementation help, refer to eBay API documentation"
+ },
+ "usage": {
+ "type": "string",
+ "description": "This value indicates whether or not the condition descriptor is required for the item condition. Currently, this field is only returned if the condition descriptor is required for the item condition. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type specifies the constraints on a condition descriptor, such as the maximum length, default condition descriptor value ID, cardinality, mode, usage, and applicable descriptor IDs."
+ },
+ "ItemConditionDescriptorValue": {
+ "type": "object",
+ "properties": {
+ "conditionDescriptorValueAdditionalHelpText": {
+ "type": "array",
+ "description": "Additional information about the the condition of the item that is not included in the conditionDescriptorValueHelpText field.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "conditionDescriptorValueConstraints": {
+ "type": "array",
+ "description": "The constraints on a condition descriptor value, such as which descriptor value IDs and Descriptor ID it is associated with.",
+ "items": {
+ "$ref": "#/components/schemas/ItemConditionDescriptorValueConstraint"
+ }
+ },
+ "conditionDescriptorValueHelpText": {
+ "type": "string",
+ "description": "A detailed description of the condition descriptor value. "
+ },
+ "conditionDescriptorValueId": {
+ "type": "string",
+ "description": "The unique identification number of a condition descriptor value associated with the conditionDescriptorValueName."
+ },
+ "conditionDescriptorValueName": {
+ "type": "string",
+ "description": "The human-readable label for the condition descriptor value associated with the conditionDescriptorValueID."
+ }
+ },
+ "description": "This type displays the possible values for the corresponding condition descriptor, along with help text and constraint information."
+ },
+ "ItemConditionDescriptorValueConstraint": {
+ "type": "object",
+ "properties": {
+ "applicableToConditionDescriptorId": {
+ "type": "string",
+ "description": "This string is returned if the corresponding condition descriptor value requires an associated condition descriptor that must also be specified in a listing. The condition descriptor ID for the associated condition descriptors is returned here."
+ },
+ "applicableToConditionDescriptorValueIds": {
+ "type": "array",
+ "description": "This array is returned if the corresponding condition descriptor value is required for one or more associated condition descriptor values that must also be specified in a listing. The condition descriptor values IDs for the associated condition descriptor values are returned here.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This type shows the constraints on a condition descriptor value, such as any associated condition descriptor ID and condition descriptor value IDs required for a listing."
+ },
+ "ItemConditionPolicy": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The category ID to which the item-condition policy applies."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree.
A category tree is a hierarchical framework of eBay categories that begins at the root node of the tree and extends to include all the child nodes in the tree. Each child node in the tree is an eBay category that is represented by a unique categoryId value. Within a category tree, the root node has no parent node and leaf nodes are nodes that have no child nodes."
+ },
+ "itemConditionRequired": {
+ "type": "boolean",
+ "description": "This flag denotes whether or not you must list the item condition in a listing for the specified category. If set to true, you must specify an item condition for the associated category."
+ },
+ "itemConditions": {
+ "type": "array",
+ "description": "The item-condition values allowed in the category.
Note: The āSeller Refurbishedā item condition (condition ID 2500) has been replaced by the 'Excellent - Refurbished', 'Very Good - Refurbished', and 'Good - Refurbished' item conditions in a select number of eBay marketplaces and categories.
Similar to the āCertified Refurbishedā item condition (condition ID 2000), a sellerās OAuth user token will have to be used instead of an OAuth application token, since each seller must go through an application and qualification process before using any of these new refurbished item conditions in supported categories. If a seller is not qualified to use the new refurbished item conditions, these item condition values will not be returned by getItemConditionPolicies.",
+ "items": {
+ "$ref": "#/components/schemas/ItemCondition"
+ }
+ }
+ }
+ },
+ "ItemConditionPolicyResponse": {
+ "type": "object",
+ "properties": {
+ "itemConditionPolicies": {
+ "type": "array",
+ "description": "A list of category IDs and the policies for how to indicate an item's condition in each of the listed categories.",
+ "items": {
+ "$ref": "#/components/schemas/ItemConditionPolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "ListingDuration": {
+ "type": "object",
+ "properties": {
+ "durationValues": {
+ "type": "array",
+ "description": "This array defines the supported time duration options available for the listing type.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "listingType": {
+ "type": "string",
+ "description": "The enumerated value returned in this field indicates the listing type for the duration value(s). For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type identifies the kind of listing and its duration periods."
+ },
+ "ListingStructurePolicy": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The category ID to which the listing-structure policy applies."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree.
A category tree is a hierarchical framework of eBay categories that begins at the root node of the tree and extends to include all the child nodes in the tree. Each child node in the tree is an eBay category that is represented by a unique categoryId value. Within a category tree, the root node has no parent node and leaf nodes are nodes that have no child nodes."
+ },
+ "variationsSupported": {
+ "type": "boolean",
+ "description": "This flag denotes whether or not the associated category supports listings with item variations. If set to true, the category does support item variations."
+ }
+ }
+ },
+ "ListingStructurePolicyResponse": {
+ "type": "object",
+ "properties": {
+ "listingStructurePolicies": {
+ "type": "array",
+ "description": "Returns a list of category IDs plus a flag indicating whether or not each listed category supports item variations.",
+ "items": {
+ "$ref": "#/components/schemas/ListingStructurePolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "ListingTypePoliciesResponse": {
+ "type": "object",
+ "properties": {
+ "listingTypePolicies": {
+ "type": "array",
+ "description": "This array contains applicable policy metadata for the leaf categories returned for the marketplace specified in the path parameter marketplace_id and optionally limited by only those leaf category IDs specified in the query parameter filter.",
+ "items": {
+ "$ref": "#/components/schemas/ListingTypePolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "An array of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type contains the selling formats for eBay listings."
+ },
+ "ListingTypePolicy": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay leaf category for which metadata is being returned."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "The unique identifier of the category tree."
+ },
+ "digitalGoodDeliveryEnabled": {
+ "type": "boolean",
+ "description": "A true value in this field indicates that the leaf category supports the listing of items (such as gift cards) that can be delivered electronically via a download link or sent to a buyer's email address."
+ },
+ "listingDurations": {
+ "type": "array",
+ "description": "An array of eBay listing types and the supported durations for the corresponding leaf category. If a specific eBay listing type does not appear for a leaf category, it indicates that the category does not support that listing type.",
+ "items": {
+ "$ref": "#/components/schemas/ListingDuration"
+ }
+ },
+ "pickupDropOffEnabled": {
+ "type": "boolean",
+ "description": "A true value in this field indicates that items listed in the category (specified in the listingTypePolicies.categoryId field) may be enabled with the 'Click and Collect' feature. With the 'Click and Collect' feature, a buyer can purchase certain items on an eBay site and collect them at a local store. Buyers are notified by eBay once their items are available. A false value in this field indicates that items listed in the category are not eligible for the 'Click and Collect' feature."
+ }
+ },
+ "description": "This type contains the policies governing the listing type by category."
+ },
+ "LocalListingDistance": {
+ "type": "object",
+ "properties": {
+ "distances": {
+ "type": "array",
+ "description": "This array indicates the radius (in miles) of the selling area for Local Market Vehicle listings.",
+ "items": {
+ "type": "integer"
+ }
+ },
+ "distanceType": {
+ "type": "string",
+ "description": "This enumerated value indicates the type of local listing distances, such as non-subscription or regular, for items listed by sellers. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type contains the kind of distance and radius of the selling area for Local Market Vehicle listings."
+ },
+ "MotorsListingPoliciesResponse": {
+ "type": "object",
+ "properties": {
+ "motorsListingPolicies": {
+ "type": "array",
+ "description": "This array contains applicable policy metadata for the leaf categories returned for the marketplace specified in the path parameter marketplace_id and optionally limited by only those leaf category IDs specified in the query parameter filter.",
+ "items": {
+ "$ref": "#/components/schemas/MotorsListingPolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "An array of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "MotorsListingPolicy": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay leaf category for which metadata is being returned."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "The unique identifier of the category tree."
+ },
+ "depositSupported": {
+ "type": "boolean",
+ "description": "This field is returned as true if the corresponding category supports the use of a deposit/down payment on a motor vehicle listing. In an AddItem call, the seller can configure a down payment for a motor vehicle listing using the PaymentDetails container."
+ },
+ "ebayMotorsProAdFormatEnabled": {
+ "type": "string",
+ "description": "Indicates whether or not eBay Motors Pro sellers can use classified ads in this category to sell their vehicles. This element is applicable for eBay Motors Pro users. For implementation help, refer to eBay API documentation"
+ },
+ "ebayMotorsProAutoAcceptEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether or not the category supports the Best Offer Auto Accept feature for eBay Motors Pro listings. This element is for eBay Motors Pro users."
+ },
+ "ebayMotorsProAutoDeclineEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether or not the category allows auto-decline for Best Offers for eBay Motors Classified Ad listings. This element is for eBay Motors Pro users."
+ },
+ "ebayMotorsProBestOfferEnabled": {
+ "type": "string",
+ "description": "This enumerated value indicates whether or not Best Offer features are supported for eBay Motors Classified Ad listings in this category. This element is for eBay Motors Pro users. For implementation help, refer to eBay API documentation"
+ },
+ "ebayMotorsProCompanyNameEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether this category supports including the company name in the seller's contact information. This element is for eBay Motors Pro users."
+ },
+ "ebayMotorsProContactByAddressEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether this category supports including the address in the seller's contact information. This element is for eBay Motors Pro users."
+ },
+ "ebayMotorsProContactByEmailEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether this category supports including an email address in the seller's contact information. This element is for eBay Motors Pro users."
+ },
+ "ebayMotorsProContactByPhoneEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether this category supports including the telephone in the seller's contact information. This element is for eBay Motors Pro users."
+ },
+ "ebayMotorsProCounterOfferEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether counter offers are allowed on Best Offers for this category in an eBay Motors Classified Ad listing. This element is for eBay Motors Pro users."
+ },
+ "ebayMotorsProPaymentMethodCheckOutEnabled": {
+ "type": "string",
+ "description": "This enumerated value indicates whether this category supports that the payment method should be displayed to the user for this category in an eBay Motors Classified Ad listing. Even if enabled, checkout may or may not be enabled. This element is for eBay Motors Pro users. For implementation help, refer to eBay API documentation"
+ },
+ "ebayMotorsProPhoneCount": {
+ "type": "integer",
+ "description": "Indicates the number of phone numbers that can be included through contact information for this category. This element is for eBay Motors Pro users.",
+ "format": "int32"
+ },
+ "ebayMotorsProSellerContactDetailsEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether this category allows seller-level contact information for eBay Motors Classified Ad listings. A value of true means seller-level contact information is available for Classified Ad listings. This element is for eBay Motors Pro users."
+ },
+ "ebayMotorsProShippingMethodEnabled": {
+ "type": "boolean",
+ "description": "Indicates if shipping options should be displayed to the user for this category in an eBay Motors Classified Ad listing. This element is for eBay Motors Pro users."
+ },
+ "ebayMotorsProStreetCount": {
+ "type": "integer",
+ "description": "This field indicates the number of street addresses allowed in contact information for this category. This element is for eBay Motors Pro users.",
+ "format": "int32"
+ },
+ "epidSupported": {
+ "type": "boolean",
+ "description": "If returned as true, this indicates the category supports the use of an eBay Product ID (e.g. ePID) to identify which motorcycles and/or scooters are compatible with a motor vehicle part or accessory. ePIDs can only be used to identify motorcycles and scooters on the Germany and UK sites."
+ },
+ "kTypeSupported": {
+ "type": "boolean",
+ "description": "This field indicates whether or not the category supports the use of a K type to identify the cars and trucks compatible with a motor vehicle part or accessory. Only the AU, DE, ES, FR, IT, and UK marketplaces support the use of K types. See Compatibility by K type for more information"
+ },
+ "localListingDistances": {
+ "type": "array",
+ "description": "This array shows the supported distances (in miles) for different types of Local Market subscription types in this category. Motor vehicle listings will be shown to buyers located within these proximities of the vehicle's location.",
+ "items": {
+ "$ref": "#/components/schemas/LocalListingDistance"
+ }
+ },
+ "localMarketAdFormatEnabled": {
+ "type": "string",
+ "description": "Specifies whether this category supports Motor Local Market Classified Ad listings. For implementation help, refer to eBay API documentation"
+ },
+ "localMarketAutoAcceptEnabled": {
+ "type": "boolean",
+ "description": "Specifies whether this category supports auto-accept for Best Offers for Motors Local Market Classified Ads."
+ },
+ "localMarketAutoDeclineEnabled": {
+ "type": "boolean",
+ "description": "Specifies whether this category supports auto-decline for Best Offers for Motors Local Market Classified Ads."
+ },
+ "localMarketBestOfferEnabled": {
+ "type": "string",
+ "description": "Indicates if Best Offer is enabled/required for Motors Local Market Classified Ad listings in this category. For implementation help, refer to eBay API documentation"
+ },
+ "localMarketCompanyNameEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether the category supports the seller's company name being specified when using Motors Local Market classified ads."
+ },
+ "localMarketContactByAddressEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether this category supports including the address in the seller's contact information."
+ },
+ "localMarketContactByEmailEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether the category supports including an email address in the seller's contact information. "
+ },
+ "localMarketContactByPhoneEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether this category supports including the telephone in the seller's contact information."
+ },
+ "localMarketCounterOfferEnabled": {
+ "type": "boolean",
+ "description": "Indicates whether counter offers are allowed on Best Offers for this category for Motors Local Market Classified Ad listings."
+ },
+ "localMarketNonSubscription": {
+ "type": "boolean",
+ "description": "Indicates whether the category supports a seller creating a Motors Local Market listing without a subscription. This feature is only available to licensed vehicle dealers."
+ },
+ "localMarketPaymentMethodCheckOutEnabled": {
+ "type": "string",
+ "description": "Indicates if the payment method should be displayed to the user for this category in an Motors Local Market Classified Ad listing. Even if enabled, checkout may or may not be enabled. For implementation help, refer to eBay API documentation"
+ },
+ "localMarketPhoneCount": {
+ "type": "integer",
+ "description": "Indicates the number of phone numbers that can be included through contact information for this category.",
+ "format": "int32"
+ },
+ "localMarketPremiumSubscription": {
+ "type": "boolean",
+ "description": "Indicates whether the category supports the Premium level subscription Motors Local Market listings. This feature is only available to licensed vehicle dealers."
+ },
+ "localMarketRegularSubscription": {
+ "type": "boolean",
+ "description": "Indicates whether the category supports the Regular level subscription to Motors Local Market listings. This feature is only available to licensed vehicle dealers."
+ },
+ "localMarketSellerContactDetailsEnabled": {
+ "type": "boolean",
+ "description": "Specifies the whether this category allows seller-level contact information for Motors Local Market Classified Ad listings."
+ },
+ "localMarketShippingMethodEnabled": {
+ "type": "boolean",
+ "description": "Indicates if shipping methods should be displayed to the user for this category in an Motors Local Market Classified Ad listing. Even if enabled, checkout may or may not be enabled."
+ },
+ "localMarketSpecialitySubscription": {
+ "type": "boolean",
+ "description": "Indicates whether the category supports the Speciality level subscription to Motors Local Market listings. This feature is only available to licensed vehicle dealers."
+ },
+ "localMarketStreetCount": {
+ "type": "integer",
+ "description": "Indicates which address option is enabled for the seller's contact information.",
+ "format": "int32"
+ },
+ "maxGranularFitmentCount": {
+ "type": "integer",
+ "description": "Indicates the maximum number of compatible applications allowed per item when adding or revising items with compatibilities provided at the most detailed granularity. For example, in Car and Truck Parts on the US site, the most granular application would include Year, Make, Model, Trim, and Engine.",
+ "format": "int32"
+ },
+ "maxItemCompatibility": {
+ "type": "integer",
+ "description": "Indicates the maximum number of compatible applications allowed per item when adding or revising items. This is relevant for specifying parts compatibility by application manually only. See Specify parts compatibility manually and Managing product compatibility for more information.",
+ "format": "int32"
+ },
+ "minItemCompatibility": {
+ "type": "integer",
+ "description": "Indicates the minimum number of required compatible applications for listing items. A value of 0 indicates it is not mandatory to specify parts compatibilities when listing.",
+ "format": "int32"
+ },
+ "nonSubscription": {
+ "type": "string",
+ "description": "The value in this field indicates whether the category supports Motors Local Market listings if the seller does not have a vehicle subscription. For implementation help, refer to eBay API documentation"
+ },
+ "premiumSubscription": {
+ "type": "string",
+ "description": "The value in this field indicates whether the category supports Motors Local Market listings if the seller has a Premium vehicle subscription. For implementation help, refer to eBay API documentation"
+ },
+ "regularSubscription": {
+ "type": "string",
+ "description": "The value in this field indicates whether the category supports Motors Local Market listings if the seller has a Regular vehicle subscription. For implementation help, refer to eBay API documentation"
+ },
+ "sellerProvidedTitleSupported": {
+ "type": "boolean",
+ "description": "This field is returned as true if the corresponding category supports the use of a seller-provided title for a motor vehicle listing on the US or Canada Motors marketplaces. A seller-provided title is a descriptive title, given by the seller, that appears below eBay's pre-filled listing title for the motor vehicle. Visually, the seller-provided title is similar to a subtitle on other types of eBay listings (non-vehicle). A seller-provided title can assist in helping buyers discover the vehicle."
+ },
+ "specialitySubscription": {
+ "type": "string",
+ "description": "The value in this field indicates whether the category supports Motors Local Market listings if the seller has a Specialty vehicle subscription. For implementation help, refer to eBay API documentation"
+ },
+ "vinSupported": {
+ "type": "boolean",
+ "description": "Indicates if Vehicle Identification Number is supported."
+ },
+ "vrmSupported": {
+ "type": "boolean",
+ "description": "Indicates if Vehicle Registration Mark is supported."
+ }
+ }
+ },
+ "MultiCompatibilityPropertyValuesRequest": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay leaf category for which to retrieve property values.
Use the getAutomotivePartsCompatibilityPolicies method to retrieve a list of categories that support parts compatibility."
+ },
+ "propertyFilters": {
+ "type": "array",
+ "description": "This array can be used to specify the compatibility properties used to limit the result set. Only values associated with the specified name-value pairs will be returned in the response.
For example, if the propertyName is set to Year and the propertyValue is set to 2022, only compatible vehicles from 2022 will be returned.
At least one property name-value pair must be used.",
+ "items": {
+ "$ref": "#/components/schemas/PropertyFilterInner"
+ }
+ },
+ "propertyNames": {
+ "type": "array",
+ "description": "This comma-delimited array specifies the names of the properties for which to retrieve associated property values.
For example, typical vehicle property names are 'Make', 'Model', 'Year', 'Engine', and 'Trim', but will vary based on the eBay marketplace and the eBay category.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This type defines the request fields used in the getMultiCompatibilityPropertyValues method."
+ },
+ "MultiCompatibilityPropertyValuesResponse": {
+ "type": "object",
+ "properties": {
+ "compatibilities": {
+ "type": "array",
+ "description": "This container defines the compatibility details associated with the specified property name value(s).",
+ "items": {
+ "$ref": "#/components/schemas/Compatibility"
+ }
+ },
+ "metadataVersion": {
+ "type": "string",
+ "description": "The version number of the metadata. This version is upticked whenever there are compatibility name changes for the specified marketplace."
+ }
+ },
+ "description": "This type defines the response fields for the getMultiCompatibilityPropertyValues method."
+ },
+ "NegotiatedPricePolicy": {
+ "type": "object",
+ "properties": {
+ "bestOfferAutoAcceptEnabled": {
+ "type": "boolean",
+ "description": "This flag denotes whether or not the category supports the setting of a price at which best offers are automatically accepted. If set to true, the category does support the setting of an automatic price for best-offers."
+ },
+ "bestOfferAutoDeclineEnabled": {
+ "type": "boolean",
+ "description": "This flag denotes whether or not the category supports the setting of an auto-decline price for best offers. If set to true, the category does support the setting of an automatic-decline price for best-offers."
+ },
+ "bestOfferCounterEnabled": {
+ "type": "boolean",
+ "description": "This flag denotes whether or not the category supports the setting for an automatic counter-offer on best offers. If set to true, the category does support the setting of an automatic counter-offer price for best-offers."
+ },
+ "categoryId": {
+ "type": "string",
+ "description": "The category ID to which the negotiated-price policies apply."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree.
A category tree is a hierarchical framework of eBay categories that begins at the root node of the tree and extends to include all the child nodes in the tree. Each child node in the tree is an eBay category that is represented by a unique categoryId value. Within a category tree, the root node has no parent node and leaf nodes are nodes that have no child nodes."
+ }
+ }
+ },
+ "NegotiatedPricePolicyResponse": {
+ "type": "object",
+ "properties": {
+ "negotiatedPricePolicies": {
+ "type": "array",
+ "description": "A list of category IDs and the policies related to negotiated-price items for each of the listed categories.",
+ "items": {
+ "$ref": "#/components/schemas/NegotiatedPricePolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "PackageLimits": {
+ "type": "object",
+ "properties": {
+ "dimensionUnit": {
+ "type": "string",
+ "description": "Unit of dimensional measurement, for example INCH or CENTIMETER. "
+ },
+ "maxGirth": {
+ "type": "number",
+ "description": "The maximum girth allowed for a package shipped through the corresponding shipping service, as measured in units of dimensionUnit."
+ },
+ "maxHeight": {
+ "type": "number",
+ "description": "The maximum height allowed for a package shipped through the corresponding shipping service, as measured in units of dimensionUnit."
+ },
+ "maxLength": {
+ "type": "number",
+ "description": "The maximum length allowed for a package shipped through the corresponding shipping service, as measured in units of dimensionUnit."
+ },
+ "maxWeight": {
+ "type": "number",
+ "description": "The maximum weight allowed for a package shipped through the corresponding shipping service, as measured in units of weightUnit."
+ },
+ "maxWidth": {
+ "type": "number",
+ "description": "The maximum width allowed for a package shipped through the corresponding shipping service, as measured in units of dimensionUnit."
+ },
+ "minGirth": {
+ "type": "number",
+ "description": "The minimum girth allowed for a package shipped through the corresponding shipping service, as measured in units of dimensionUnit."
+ },
+ "minHeight": {
+ "type": "number",
+ "description": "The minimum height allowed for a package shipped through the corresponding shipping service, as measured in units of dimensionUnit."
+ },
+ "minLength": {
+ "type": "number",
+ "description": "The minimum length allowed for a package shipped through the corresponding shipping service, as measured in units of dimensionUnit."
+ },
+ "minWeight": {
+ "type": "number",
+ "description": "The minimum weight allowed for a package shipped through the corresponding shipping service, as measured in units of weightUnit."
+ },
+ "minWidth": {
+ "type": "number",
+ "description": "The minimum width allowed for a package shipped through the corresponding shipping service, as measured in units of dimensionUnit."
+ },
+ "weightUnit": {
+ "type": "string",
+ "description": "Unit of weight measurement, for example KILOGRAM or OUNCE. "
+ }
+ },
+ "description": "The packageLimits field is used to specify the physical constraints and measurement units of packages, ensuring compliance with various shipping requirements."
+ },
+ "Pagination": {
+ "type": "object",
+ "properties": {
+ "count": {
+ "type": "integer",
+ "description": "The number of results showing on the current page of results.",
+ "format": "int32"
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The max number of entries that can be returned on a single page.",
+ "format": "int32"
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of items that will be skipped in the result set before returning the first item in the paginated response.",
+ "format": "int32"
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of results in a result set.",
+ "format": "int32"
+ }
+ },
+ "description": "This type defines the pagination settings for a result set."
+ },
+ "PaginationInput": {
+ "type": "object",
+ "properties": {
+ "limit": {
+ "type": "integer",
+ "description": "The max number of items, from the current result set, returned on a single page.
Note: For getProductCompatibilities, the max value is 100. If no limit is specified, this field defaults to the max value.",
+ "format": "int32"
+ },
+ "offset": {
+ "type": "integer",
+ "description": "The number of items that will be skipped in the result set before returning the first item in the paginated response.
Combine offset with limit to control the items returned in the response. For example, if you supply an offset of 10 and a limit of 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0",
+ "format": "int32"
+ }
+ },
+ "description": "This type defines the fields used to control the pagination of the result set."
+ },
+ "Pictogram": {
+ "type": "object",
+ "properties": {
+ "pictogramId": {
+ "type": "string",
+ "description": "The identifier of the pictogram. For sample values, see Pictogram sample values."
+ },
+ "pictogramDescription": {
+ "type": "string",
+ "description": "The description of the pictogram localized to the default language of the marketplace. For sample values, see Pictogram sample values."
+ },
+ "pictogramUrl": {
+ "type": "string",
+ "description": "The URL of the pictogram."
+ }
+ },
+ "description": "A type that describes pictograms for hazardous materials labels."
+ },
+ "ProductIdentifier": {
+ "type": "object",
+ "properties": {
+ "ean": {
+ "type": "string",
+ "description": "The EAN of the item, if applicable. EAN is the European Article Number, a barcode standard for retail product labeling primarily used outside of North America."
+ },
+ "epid": {
+ "type": "string",
+ "description": "The ePID (eBay Product Identifier) of the item, if applicable. ePID is a unique identifier used by eBay to track products in its catalog.
Use the getProduct method of the Catalog API to retrieve the ePID of an item."
+ },
+ "isbn": {
+ "type": "string",
+ "description": "The ISBN of the item, if applicable. ISBN is the International Standard Book Number, a unique identifier for books."
+ },
+ "productId": {
+ "type": "string",
+ "description": "The product ID of the item, if applicable. The product ID is a general term for a unique identifier assigned to a product."
+ },
+ "upc": {
+ "type": "string",
+ "description": "The UPC of the item, if applicable. UPC stands for Universal Product Code, a unique identifier for products, primarily in North America."
+ }
+ },
+ "description": "This type defines the supported product identifiers."
+ },
+ "ProductRequest": {
+ "type": "object",
+ "properties": {
+ "applicationPropertyFilters": {
+ "type": "array",
+ "description": "This array is used to filter the properties of an application, such as a vehicle's make or model, that will be returned in the response.
Application property filters are specified as name-value pairs. Only products compatible with these name-value pairs will be returned.",
+ "items": {
+ "$ref": "#/components/schemas/PropertyFilterInner"
+ }
+ },
+ "dataset": {
+ "type": "array",
+ "description": "This array defines the type of properties that are returned for the catalog-enabled category.
For example, if you specify Searchable, the compatibility details will contain properties that can be used to search for products, such as make or model.
Note: This field cannot be used alongside dataPropertyName. If both are used, an error will occur.
Valid values:DisplayableProductDetails: Properties for use in a user interface to describe products.DisplayableSearchResults: Properties for use in results for product searches.Searchable: Properties for use in searches.Sortable: Properties that are suitable for sorting.
Default: DisplayableSearchResults",
+ "items": {
+ "type": "string"
+ }
+ },
+ "datasetPropertyName": {
+ "type": "array",
+ "description": "This comma-delimted array can be used to define the specific property name(s) that will be returned in the response.
For example, if you specify Engine, the result set will only contain engines that are compatible with the input criteria.
Note: This array cannot be used alongside dataset. If both are used, an error will occur.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "disabledProductFilter": {
+ "description": "This container can be used to specify whether or not to filter out products which are disabled for selling on eBay and/or disabled for product review. ",
+ "$ref": "#/components/schemas/DisabledProductFilter"
+ },
+ "paginationInput": {
+ "description": "This container controls the pagination of the result set.",
+ "$ref": "#/components/schemas/PaginationInput"
+ },
+ "productIdentifier": {
+ "description": "This container is used to provide unique identifier for the product. The product identifier consists of an identifier type and value, and are unique across all sites.",
+ "$ref": "#/components/schemas/ProductIdentifier"
+ },
+ "sortOrders": {
+ "type": "array",
+ "description": "This array controls the sort order of compatibility properties.",
+ "items": {
+ "$ref": "#/components/schemas/SortOrderInner"
+ }
+ }
+ },
+ "description": "This type defines the request fields for the getProductCompatibilities method."
+ },
+ "ProductResponse": {
+ "type": "object",
+ "properties": {
+ "compatibilityDetails": {
+ "type": "array",
+ "description": "This container provides compatibility details for the specified product.",
+ "items": {
+ "$ref": "#/components/schemas/ProductResponseCompatibilityDetails"
+ }
+ },
+ "pagination": {
+ "description": "This container returns the pagination settings for the result set.",
+ "$ref": "#/components/schemas/Pagination"
+ }
+ },
+ "description": "This type defines the response fields for the getProductCompatibilities method."
+ },
+ "ProductResponseCompatibilityDetails": {
+ "type": "object",
+ "properties": {
+ "noteDetails": {
+ "type": "array",
+ "description": "This array returns additional comments about the corresponding product in the form of name-value pairs.",
+ "items": {
+ "$ref": "#/components/schemas/PropertyFilterInner"
+ }
+ },
+ "productDetails": {
+ "type": "array",
+ "description": "This array returns details about the product in the form of name-value pairs. ",
+ "items": {
+ "$ref": "#/components/schemas/PropertyValues"
+ }
+ }
+ },
+ "description": "This type defines the compatibility details for a product."
+ },
+ "ProductSafetyLabelPictogram": {
+ "type": "object",
+ "properties": {
+ "pictogramDescription": {
+ "type": "string",
+ "description": "The description of the pictogram localized to the default language of the marketplace. "
+ },
+ "pictogramId": {
+ "type": "string",
+ "description": "The identifier of the pictogram."
+ },
+ "pictogramUrl": {
+ "type": "string",
+ "description": "The URL of the pictogram."
+ }
+ },
+ "description": "A type that describes pictograms for product safety labels."
+ },
+ "ProductSafetyLabelStatement": {
+ "type": "object",
+ "properties": {
+ "statementDescription": {
+ "type": "string",
+ "description": "The description of the statement localized to the default language of the marketplace. "
+ },
+ "statementId": {
+ "type": "string",
+ "description": "The identifier of the statement."
+ }
+ },
+ "description": "A type that describes statements for product safety labels."
+ },
+ "ProductSafetyLabelsResponse": {
+ "type": "object",
+ "properties": {
+ "pictograms": {
+ "type": "array",
+ "description": "This array contains a list of pictograms of product safety labels for the specified marketplace.",
+ "items": {
+ "$ref": "#/components/schemas/ProductSafetyLabelPictogram"
+ }
+ },
+ "statements": {
+ "type": "array",
+ "description": "This array contains available product safety labels statements for the specified marketplace. ",
+ "items": {
+ "$ref": "#/components/schemas/ProductSafetyLabelStatement"
+ }
+ }
+ },
+ "description": "A type that defines the response fields for the getProductSafetyLabels method."
+ },
+ "PropertyFilterInner": {
+ "type": "object",
+ "properties": {
+ "propertyName": {
+ "type": "string",
+ "description": "The name of the property being described.
For example, typical vehicle property names are 'Make', 'Model', 'Year', 'Engine', and 'Trim', but will vary based on the eBay marketplace and the eBay category. Use the getCompatibilityPropertyNames method to retrieve valid property names for a specified category."
+ },
+ "propertyValue": {
+ "type": "string",
+ "description": "The value for the property specified in the properyName field.
For example, if the propertyName is Make, then the propertyValue will be the specific make of the vehicle, such as Toyota. Use the getCompatibilityPropertyValues to retreive valid property values associated with a specified property name."
+ },
+ "unitOfMeasurement": {
+ "type": "string",
+ "description": "The unit of measurement of the property being described, if applicable."
+ },
+ "url": {
+ "type": "string",
+ "description": "The URL associated with the property being described, if applicable."
+ }
+ },
+ "description": "This type is used to define the available compatibility property filters."
+ },
+ "PropertyNamesRequest": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay leaf category for which to retrieve compatibility property names. This category must be a valid eBay category on the specified eBay marketplace, and the category must support parts compatibility.
Use the getAutomotivePartsCompatibilityPolicies method to retrieve a list of categories that support parts compatibility."
+ },
+ "dataset": {
+ "type": "array",
+ "description": "This array defines the properties that will be returned for the compatibility-enabled category.
For example, if you specify Searchable, the compatibility details will contain properties that can be used to search for products, such as make or model.
Valid values:DisplayableProductDetails: Properties for use in a user interface to describe products.DisplayableSearchResults: Properties for use in results for product searches.Searchable: Properties for use in searches.Sortable: Properties that are suitable for sorting.
Default: DisplayableSearchResults",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This type defines the request fields for the getCompatibilityPropertyNames method."
+ },
+ "PropertyNamesResponse": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay category specified in the request."
+ },
+ "properties": {
+ "type": "array",
+ "description": "This array contains all of the properties for the specified category.",
+ "items": {
+ "$ref": "#/components/schemas/PropertyNamesResponseProperties"
+ }
+ }
+ },
+ "description": "This type defines the fields returned in the getCompatibilityPropertyNames method."
+ },
+ "PropertyNamesResponseProperties": {
+ "type": "object",
+ "properties": {
+ "dataset": {
+ "type": "string",
+ "description": "This field defines the types of properties are returned for the specified catalog-enabled category.
Valid values:DisplayableProductDetails: Properties for use in a user interface to describe products.DisplayableSearchResults: Properties for use in results for product searches.Searchable: Properties for use in searches.Sortable: Properties that are suitable for sorting.
"
+ },
+ "propertyNames": {
+ "type": "array",
+ "description": "This array specifies the names of the properties associated with the specified category in the specified marketplace.
For example, typical vehicle property names are 'Make', 'Model', 'Year', 'Engine', and 'Trim', but will vary based on the eBay marketplace and the eBay category.",
+ "items": {
+ "$ref": "#/components/schemas/PropertyNamesResponsePropertyNames"
+ }
+ }
+ },
+ "description": "This type defines the properties and dataset for a specified category."
+ },
+ "PropertyNamesResponsePropertyNameMetadata": {
+ "type": "object",
+ "properties": {
+ "displaySequence": {
+ "type": "integer",
+ "description": "The numeric value indicating the ordering position of the property.",
+ "format": "int32"
+ }
+ },
+ "description": "This type defines the property name metadata."
+ },
+ "PropertyNamesResponsePropertyNames": {
+ "type": "object",
+ "properties": {
+ "propertyDisplayName": {
+ "type": "string",
+ "description": "The display name of a property. This is the localized name of the compatible property."
+ },
+ "propertyName": {
+ "type": "string",
+ "description": "The canonical name of a property. This value is used as part of the name-value pairs used to specify compatibility."
+ },
+ "propertyNameMetadata": {
+ "description": "The metadata for a property.",
+ "$ref": "#/components/schemas/PropertyNamesResponsePropertyNameMetadata"
+ }
+ },
+ "description": "This type defines the fields associated with a property name."
+ },
+ "PropertyValues": {
+ "type": "object",
+ "properties": {
+ "propertyName": {
+ "type": "string",
+ "description": "The name of the property.
For example, typical vehicle property names are 'Make', 'Model', 'Year', 'Engine', and 'Trim', but will vary based on the eBay marketplace and the eBay category."
+ },
+ "propertyValue": {
+ "type": "string",
+ "description": "The value for the property specified in the properyName field.
For example, if the propertyName is make, then the propertyValue will be the specific make of the vehicle, such as Toyota."
+ }
+ },
+ "description": "This type defines the name-value pair associated with a property value."
+ },
+ "PropertyValuesRequest": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay leaf category for which to retrieve compatibility property values. This category must be a valid eBay category on the specified eBay marketplace, and the category must support parts compatibility.
Use the getAutomotivePartsCompatibilityPolicies method to retrieve a list of categories that support parts compatibility."
+ },
+ "propertyFilters": {
+ "type": "array",
+ "description": "This array can be used to specify the compatibility properties used limit the result set. Only values associated with the specified name-value pairs will be returned in the response.
For example, if the propertyName is set to Make and the propertyValue is set to Honda, only compatible Honda vehicles will be returned.",
+ "items": {
+ "$ref": "#/components/schemas/PropertyFilterInner"
+ }
+ },
+ "propertyName": {
+ "type": "string",
+ "description": "This field specifies the name of the property for which to retrieve associated property values.
For example, typical vehicle property names are 'Make', 'Model', 'Year', 'Engine', and 'Trim', but will vary based on the eBay marketplace and the eBay category. Use the getCompatibilityPropertyNames method to retrieve valid property names for a specified category."
+ },
+ "sortOrder": {
+ "type": "string",
+ "description": "This field specifies the sort order for the property values in the result set.
Valid values:Note: If no search order is specified, values are sorted in ascending order."
+ }
+ },
+ "description": "This type defines the request fields used in the getCompatibilityPropertyValues method."
+ },
+ "PropertyValuesResponse": {
+ "type": "object",
+ "properties": {
+ "metadataVersion": {
+ "type": "string",
+ "description": "The version number of the metadata. This version is upticked whenever there are compatibility name changes for the specified marketplace."
+ },
+ "propertyName": {
+ "type": "string",
+ "description": "The name of the property specified in the request."
+ },
+ "propertyValues": {
+ "type": "array",
+ "description": "This array specifies the property values associated with the specified propertyName, in the specified category.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "description": "This type defines the response fields used in the getCompatibilityPropertyValues method."
+ },
+ "RegulatoryAttribute": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "A unique value identifying a specific regulatory attribute. For implementation help, refer to eBay API documentation"
+ },
+ "usage": {
+ "type": "string",
+ "description": "The enumeration value in this field indicates whether the corresponding attribute is recommended or required for the corresponding leaf category. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "A type that defines the attributes of a regulatory policy."
+ },
+ "RegulatoryPolicy": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the leaf category to which the corresponding policies pertain."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "The unique identifier of the category tree, which reflects the specified marketplace."
+ },
+ "supportedAttributes": {
+ "type": "array",
+ "description": "A list of supported regulatory attributes for this marketplace.",
+ "items": {
+ "$ref": "#/components/schemas/RegulatoryAttribute"
+ }
+ }
+ },
+ "description": "A type that defines the regulatory policy."
+ },
+ "RegulatoryPolicyResponse": {
+ "type": "object",
+ "properties": {
+ "regulatoryPolicies": {
+ "type": "array",
+ "description": "A list of eBay policies that define whether or not you must include required regulatory information for leaf categories on the given marketplace.",
+ "items": {
+ "$ref": "#/components/schemas/RegulatoryPolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "A type that defines the response fields for the getRegulatoryPolicies method."
+ },
+ "ReturnPolicy": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The category ID to which the return policies apply."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree.
A category tree is a hierarchical framework of eBay categories that begins at the root node of the tree and extends to include all the child nodes in the tree. Each child node in the tree is an eBay category that is represented by a unique categoryId value. Within a category tree, the root node has no parent node and leaf nodes are nodes that have no child nodes."
+ },
+ "domestic": {
+ "description": "This complex type defines the category policies related to domestic item returns.",
+ "$ref": "#/components/schemas/ReturnPolicyDetails"
+ },
+ "international": {
+ "description": "This complex type defines the category policies related to international item returns.",
+ "$ref": "#/components/schemas/ReturnPolicyDetails"
+ },
+ "required": {
+ "type": "boolean",
+ "description": "If set to true, this flag indicates that you must specify a return policy for items listed in the associated category.
Note that not accepting returns (setting returnsAcceptedEnabled to false) is a valid return policy."
+ }
+ }
+ },
+ "ReturnPolicyDetails": {
+ "type": "object",
+ "properties": {
+ "policyDescriptionEnabled": {
+ "type": "boolean",
+ "description": "If set to true, this flag indicates you can supply a detailed return policy description within your return policy (for example, by populating the returnInstructions field in the Account API's createReturnPolicy). User-supplied return policy details are allowed only in the DE, ES, FR, and IT marketplaces.
Note: Depending on the API used to setup your return policy, return instructions are defined differently."
+ },
+ "refundMethods": {
+ "type": "array",
+ "description": "A list of refund methods allowed for the associated category.
Note: Depending on the API used to setup your return policy, available refund methods are defined differently.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "returnMethods": {
+ "type": "array",
+ "description": "A list of return methods allowed for the associated category.
Note: Depending on the API used to setup your return policy, available return methods are defined differently.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ },
+ "returnPeriods": {
+ "type": "array",
+ "description": "A list of return periods allowed for the associated category.
Note: Depending on the API used to setup your return policy, return periods are defined differently.",
+ "items": {
+ "$ref": "#/components/schemas/TimeDuration"
+ }
+ },
+ "returnsAcceptanceEnabled": {
+ "type": "boolean",
+ "description": "A value of true in this field indicates that return policies are applicable to the corresponding leaf category.
Note: Depending on the API used to setup your return policy, whether or not you accept returns is configured as follows:"
+ },
+ "returnShippingCostPayers": {
+ "type": "array",
+ "description": "A list of allowed values for who pays for the return shipping cost.
Note that for SNAD returns, the seller is always responsible for the return shipping cost.
Note: Depending on the API used to setup your return policy, specifiying that the buyer or seller is responsible for paying for return shipping costs is defined differently.",
+ "items": {
+ "type": "string",
+ "description": " For implementation help, refer to eBay API documentation"
+ }
+ }
+ },
+ "description": "This container defines the category policies that relate to domestic and international return policies (the return shipping is made via a domestic or an international shipping service, respectively)."
+ },
+ "ReturnPolicyResponse": {
+ "type": "object",
+ "properties": {
+ "returnPolicies": {
+ "type": "array",
+ "description": "A list of elements, where each contains a category ID and a flag that indicates whether or not listings in that category require a return policy.",
+ "items": {
+ "$ref": "#/components/schemas/ReturnPolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "SalesTaxJurisdiction": {
+ "type": "object",
+ "properties": {
+ "salesTaxJurisdictionId": {
+ "type": "string",
+ "description": "The unique ID for a sales-tax jurisdiction.
Important! When countryCode is set to US, IDs for all 50 states, Washington, DC, and all US territories will be returned. However, the only salesTaxJurisdictionId values currently supported are:
AS (American Samoa)GU (GuamMP Northern Mariana IslandsPW (Palau)VI (US Virgin Islands)
UPS, FedEx, and USPS."
+ },
+ "shippingCarrier": {
+ "type": "string",
+ "description": "An enumerated value describing the shipping carrier returned, for example, UPS, FedEx, and USPS. These values are needed when providing shipment tracking information for each specific shipping carrier."
+ }
+ },
+ "description": "This type provides applicable shipping carrier metadata for the marketplace."
+ },
+ "ShippingCarrierResponse": {
+ "type": "object",
+ "properties": {
+ "shippingCarriers": {
+ "type": "array",
+ "description": "A list of shipping carriers available for the marketplace.",
+ "items": {
+ "$ref": "#/components/schemas/ShippingCarrier"
+ }
+ }
+ },
+ "description": "This type provides applicable shipping carrier metadata for returned for the marketplace."
+ },
+ "ShippingExcludeLocation": {
+ "type": "object",
+ "properties": {
+ "description": {
+ "type": "string",
+ "description": "The localized location name."
+ },
+ "location": {
+ "type": "string",
+ "description": " The location or region to be excluded. Countries are returned through ISO 3166 codes. This field may also include continents and other larger geographical regions (for example, the Middle East, Southeast Asia), as well as domestic/special locations (like APO/FPO, PO Box, Alaska/Hawaii). The values returned in this field are used in fulfillment business policies (such as in regionName) or through the ExcludeShipToLocation field in an AddItem call."
+ },
+ "region": {
+ "type": "string",
+ "description": "The region of the excluded shipping area specified, such as:
Africa Americas Asia Central America and Caribbean Europe Middle East North America Oceania South America Southeast Asia
"
+ }
+ },
+ "description": "This type provides applicable locations or region codes to be excluded set by the seller."
+ },
+ "ShippingExcludeLocationResponse": {
+ "type": "object",
+ "properties": {
+ "excludeShippingLocations": {
+ "type": "array",
+ "description": "The complete list of geographical regions, countries, domestic areas, and special locations for the specified eBay marketplace that the seller has designated as excluded shipping locations.",
+ "items": {
+ "$ref": "#/components/schemas/ShippingExcludeLocation"
+ }
+ }
+ },
+ "description": "This type provides applicable locations or region codes to be excluded."
+ },
+ "ShippingHandlingTime": {
+ "type": "object",
+ "properties": {
+ "description": {
+ "type": "string",
+ "description": "The localized description of the maximum handling time."
+ },
+ "extendedHandling": {
+ "type": "boolean",
+ "description": "This field is only returned if its value is true. If returned, it indicates that the corresponding handling time is considered extended handling for the marketplace. Extended handling times may be used for freight shipping, but should generally be avoided if possible, as they might adversely affect the buying decisions of potential customers."
+ },
+ "maxHandlingTime": {
+ "type": "integer",
+ "description": "The integer value returned in this field indicates the maximum number of business days that the eBay site allows as a seller's handling time measured from when the buyer pays for the order. For example, if the maxHandlingTime value is set to 1 and a buyer pays for the order on a Wednesday, the seller would have to ship the item by the next day (Thursday).
A maxHandlingTime value of 0 indicates same day handling for an item. In this case, the seller's handling time commitment depends on the order cut off time set in the seller's user preferences. This defaults to 2:00 PM local time on most eBay sites. For orders placed (and cleared payment received) before the local order cut off time, the item must be shipped by the end of the current day. For orders completed on or after the order cut off time, the item must be shipped by the end of the following day (excluding weekends and local holidays).",
+ "format": "int32"
+ }
+ },
+ "description": "This type provides applicable shipping handling time metadata."
+ },
+ "ShippingHandlingTimeResponse": {
+ "type": "object",
+ "properties": {
+ "handlingTimes": {
+ "type": "array",
+ "description": "A list of supported handling times for the marketplace.",
+ "items": {
+ "$ref": "#/components/schemas/ShippingHandlingTime"
+ }
+ }
+ },
+ "description": "This type provides applicable shipping handling times returned for the specified marketplace."
+ },
+ "ShippingLocation": {
+ "type": "object",
+ "properties": {
+ "description": {
+ "type": "string",
+ "description": "The localized location name."
+ },
+ "shippingLocation": {
+ "type": "string",
+ "description": "The name or abbreviation of the shipping location or region. Countries are returned through ISO 3166 codes. This field may also include continents and other larger geographical regions (for example, the Middle East, Southeast Asia), as well as domestic/special locations (like APO/FPO, PO Box, Alaska/Hawaii). The values returned in this field are used in fulfillment business policies (such as in regionName) or through the ExcludeShipToLocation field in an AddItem call."
+ }
+ },
+ "description": "This type provides applicable shipping location metadata."
+ },
+ "ShippingLocationResponse": {
+ "type": "object",
+ "properties": {
+ "shippingLocations": {
+ "type": "array",
+ "description": "The complete list of geographical regions, countries, domestic areas, and special locations for the specified eBay marketplace that can be set as shipping locations.",
+ "items": {
+ "$ref": "#/components/schemas/ShippingLocation"
+ }
+ }
+ },
+ "description": "This type provides applicable shipping location metadata returned."
+ },
+ "ShippingPoliciesResponse": {
+ "type": "object",
+ "properties": {
+ "shippingPolicies": {
+ "type": "array",
+ "description": "This array contains applicable policy metadata for the leaf categories returned for the marketplace specified in the path parameter marketplace_id and optionally limited by only those leaf category IDs specified in the query parameter filter.",
+ "items": {
+ "$ref": "#/components/schemas/ShippingPolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "An array of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "This type provides fields applicable for shipping policy metadata for the leaf categories returned for the marketplace."
+ },
+ "ShippingPolicy": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay leaf category for which metadata is being returned."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "The unique identifier of the category tree."
+ },
+ "globalShippingEnabled": {
+ "type": "boolean",
+ "description": "Indicates if the Global Shipping Program (GSP) is supported for the category. Note: GSP is only supported by the eBay UK marketplace (EBAY_GB).
"
+ },
+ "group1MaxFlatShippingCost": {
+ "description": "Returns the applicable max cap per shipping cost for shipping service group1.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "group2MaxFlatShippingCost": {
+ "description": "Returns the applicable max cap per shipping cost for shipping service group2.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "group3MaxFlatShippingCost": {
+ "description": "Returns the applicable max cap per shipping cost for shipping service group3.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "handlingTimeEnabled": {
+ "type": "boolean",
+ "description": "Indicates if a seller's stated handling time is enabled for a category. A handling time is generally needed for items that are shipped to the buyer, but not necessarily applicable to freight shipping or local pickup."
+ },
+ "maxFlatShippingCost": {
+ "description": "The maximum cost the seller can charge for the first domestic flat-rate shipping service. Mutually exclusive with the GroupNMaxFlatShippingCost elements.",
+ "$ref": "#/components/schemas/Amount"
+ },
+ "shippingTermsRequired": {
+ "type": "boolean",
+ "description": "Indicates whether the category requires sellers to specify shipping details at listing time."
+ }
+ }
+ },
+ "ShippingService": {
+ "type": "object",
+ "properties": {
+ "description": {
+ "type": "string",
+ "description": "This field returns the localized name of the shipping service."
+ },
+ "internationalService": {
+ "type": "boolean",
+ "description": "A value of true indicates that the shipping service is international. An international shipping service option is required if an item is being shipped from one country (origin) to another (destination)."
+ },
+ "maxShippingTime": {
+ "type": "integer",
+ "description": "This value indicates the maximum number of business days that it takes the shippingCarrier to ship an item using the corresponding shippingService. ",
+ "format": "int32"
+ },
+ "minShippingTime": {
+ "type": "integer",
+ "description": "This value indicates the minimum number of business days that it takes the shippingCarrier to ship an item using the corresponding shippingService. ",
+ "format": "int32"
+ },
+ "packageLimits": {
+ "description": "This container provides name-value pairs that specify physical constraints and measurement units of packages for the shippingCarrier and the corresponding shippingService. An empty container is returned if the shipping service does not have any package limits defined.",
+ "$ref": "#/components/schemas/PackageLimits"
+ },
+ "shippingCarrier": {
+ "type": "string",
+ "description": "The code for the shipping carrier returned, for example, UPS, FedEx, and USPS."
+ },
+ "shippingCategory": {
+ "type": "string",
+ "description": "The shipping category of the shipping service including: ECONOMY, STANDARD, EXPEDITED, ONE_DAY, PICKUP, and other similar categories."
+ },
+ "shippingCostTypes": {
+ "type": "array",
+ "description": "A list of shipping cost types that this shipping service option supports. For example, FLAT_RATE, CALCULATED, and FREIGHT.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "shippingService": {
+ "type": "string",
+ "description": "The name of the shipping service. The shipping service named here can only be used in listings or in business policies if validForSellingFlow is true. The value returned in this field is used in listing APIs and business policies to set the shipping service."
+ },
+ "validForSellingFlow": {
+ "type": "boolean",
+ "description": "A value of true indicates that the shippingService can be set as an available shipping service in the listing or through the fulfillment business policy."
+ }
+ },
+ "description": "This type provides applicable shipping service metadata."
+ },
+ "ShippingServiceResponse": {
+ "type": "object",
+ "properties": {
+ "shippingServices": {
+ "type": "array",
+ "description": "A complete list of shipping service options that can be used on the marketplace for shipping items.",
+ "items": {
+ "$ref": "#/components/schemas/ShippingService"
+ }
+ }
+ },
+ "description": "This type provides applicable shipping service metadata returned."
+ },
+ "SignalWord": {
+ "type": "object",
+ "properties": {
+ "signalWordId": {
+ "type": "string",
+ "description": "The identifier of the signal word. For more information, see Signal word information."
+ },
+ "signalWordDescription": {
+ "type": "string",
+ "description": "The description of the signal word localized to the default language of the marketplace. For more information, see Signal word information."
+ }
+ },
+ "description": "A type that describes signal words for hazardous materials labels."
+ },
+ "SiteVisibilityPoliciesResponse": {
+ "type": "object",
+ "properties": {
+ "siteVisibilityPolicies": {
+ "type": "array",
+ "description": "This array contains applicable policy metadata for the leaf categories returned for the marketplace specified in the path parameter marketplace_id and optionally limited by only those leaf category IDs specified in the query parameter filter.",
+ "items": {
+ "$ref": "#/components/schemas/SiteVisibilityPolicy"
+ }
+ },
+ "warnings": {
+ "type": "array",
+ "description": "An array of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
+ "items": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ },
+ "description": "A type that contains eBay international site visibility policy metadata fields."
+ },
+ "SiteVisibilityPolicy": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay leaf category for which metadata is being returned."
+ },
+ "categoryTreeId": {
+ "type": "string",
+ "description": "The unique identifier of the category tree."
+ },
+ "crossBorderTradeAustraliaEnabled": {
+ "type": "boolean",
+ "description": "If true, the category supports specifying that listings of a seller on the UK marketplace can pass in Australia as a value in a field to expose that item on the eBay Australia site (ebay.com.au). For more information, see Cross-border trading."
+ },
+ "crossBorderTradeGBEnabled": {
+ "type": "boolean",
+ "description": "If true, the category supports specifying that listings of a seller on the US or Canada merketplaces can pass in UK as a value in a field to expose that item on the eBay UK (ebay.co.uk) and eBay IE (ebay.ie) sites. For more information, see Cross-border trading."
+ },
+ "crossBorderTradeNorthAmericaEnabled": {
+ "type": "boolean",
+ "description": "If true, the category supports specifying that listings of a seller on the US or Canada merketplaces can pass in North America as a value in a field to expose that item on the eBay US (ebay.com) and eBay Canada (ebay.ca) sites (English). For more information, see Cross-border trading. "
+ }
+ },
+ "description": "A type that contains eBay international cross border trade policy metadata fields."
+ },
+ "SortOrderInner": {
+ "type": "object",
+ "properties": {
+ "sortOrder": {
+ "description": "This container is used to define the property to be used in the sorting.",
+ "$ref": "#/components/schemas/SortOrderProperties"
+ },
+ "sortPriority": {
+ "type": "string",
+ "description": "The priority of the specified sort order provided.
For example, when a property is assigned Sort1, its values are sorted first. Values for the property assigned Sort2 are sorted second, and so on.
Valid values:Sort1Sort2Sort3Sort4Sort5
"
+ }
+ },
+ "description": "This type is used to provide the sort order of compatibility properties returned in the response."
+ },
+ "SortOrderProperties": {
+ "type": "object",
+ "properties": {
+ "order": {
+ "type": "string",
+ "description": "Defines the order of the sort.
Valid values:"
+ },
+ "propertyName": {
+ "type": "string",
+ "description": "The name of the searchable property to be used for sorting.
For example, typical vehicle property names are 'Make', 'Model', 'Year', 'Engine', and 'Trim', but will vary based on the eBay marketplace and the eBay category."
+ }
+ },
+ "description": "This type is used to define the property to be used in sorting. "
+ },
+ "SpecificationRequest": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of the eBay leaf category for which compatibility details are being retrieved. This category must be a valid eBay category on the specified eBay marketplace, and the category must support parts compatibility for cars, trucks, or motorcycles.
Use the getAutomotivePartsCompatibilityPolicies method to retrieve a list of categories that support parts compatibility by specification. For the categories in the response that support compatibility by specification, youāll see SPECIFICATIONS as the value for the compatibilityBasedOn field "
+ },
+ "compatibilityPropertyFilters": {
+ "type": "array",
+ "description": "This comma-delimited array can be used to restrict the number of compatible application name-value pairs returned in the response by specifying the properties that the seller wishes to be included in the response.
Only compatible applications with the specified properties will be returned. Properties that can be specified here include make, model, year, and trim.",
+ "items": {
+ "$ref": "#/components/schemas/PropertyFilterInner"
+ }
+ },
+ "dataset": {
+ "type": "string",
+ "description": "This field can be used to define the type of properties that will be returned in the response.
For example, if you specify Searchable, the compatibility details will contain properties that can be used to search for products, such as make or model.
Note: This field cannot be used alongside dataPropertyName. If both are used, an error will occur.
Valid values:DisplayableProductDetails: Properties for use in a user interface to describe products.DisplayableSearchResults: Properties for use in results for product searches.Searchable: Properties for use in searches.Sortable: Properties that are suitable for sorting.
Default value: DisplayableSearchResults"
+ },
+ "datasetPropertyName": {
+ "type": "array",
+ "description": "This comma-delimited array can be used to define the specific property name(s) that will be returned in the response.
For example, if you specify Engine, the result set will only contain engines that are compatible with the input criteria.
Note: This array cannot be used alongside dataset. If both are used, an error will occur.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "exactMatch": {
+ "type": "boolean",
+ "description": "This boolean can be used to specify that the compatibilities returned in the response are to be defined by an exact match on the input value of specification properties.
By default, an expanded compatibility match is done when it applies, such as for Load Index, where a compatible vehicle is one that has a load index requirement that is less than or equal to the input. By specifying this field as true, only exact matches are returned."
+ },
+ "paginationInput": {
+ "description": "Important! Pagination is not yet supported by this method. If this container is included in the request, it will be ignored.
Note: If no sort order is specified through this field, the default sort order of popularity descending is applied.",
+ "items": {
+ "$ref": "#/components/schemas/SortOrderInner"
+ }
+ },
+ "specifications": {
+ "type": "array",
+ "description": "This array defines the specifications of the part, in the form of name-value pairs, for which compatible applications will be retrieved.",
+ "items": {
+ "$ref": "#/components/schemas/PropertyFilterInner"
+ }
+ }
+ },
+ "description": "This type provides the properties and specifications to use to search for compatibilities."
+ },
+ "SpecificationResponse": {
+ "type": "object",
+ "properties": {
+ "compatibilityDetails": {
+ "type": "array",
+ "description": "This container returns the list of all compatible application name-value pairs for the given filter criteria.",
+ "items": {
+ "$ref": "#/components/schemas/Compatibility"
+ }
+ },
+ "pagination": {
+ "description": "Important! Not currently returned. For future use.
A span of time is defined when you apply the value specified in the value field to the value specified for unit.
Time-measurement units can be YEAR, MONTH, DAY, and so on. See TimeDurationUnitEnum for a complete list of possible time-measurement units. For implementation help, refer to eBay API documentation"
+ },
+ "value": {
+ "type": "integer",
+ "description": "An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.",
+ "format": "int32"
+ }
+ },
+ "description": "A complex type that specifies a period of time using a specified time-measurement unit."
}
- },
- "authorizationCode": {
- "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
- "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
- "scopes": {
- "https://api.ebay.com/oauth/api_scope/sell.inventory": "View and manage your inventory and offers"
+ },
+ "securitySchemes": {
+ "api_auth": {
+ "type": "oauth2",
+ "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
+ "flows": {
+ "clientCredentials": {
+ "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
+ "scopes": {
+ "https://api.ebay.com/oauth/api_scope": "View public data from eBay"
+ }
+ },
+ "authorizationCode": {
+ "authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
+ "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
+ "scopes": {
+ "https://api.ebay.com/oauth/api_scope/sell.inventory": "View and manage your inventory and offers"
+ }
+ }
+ }
}
- }
}
- }
}
- }
}
\ No newline at end of file
diff --git a/specs/sell_negotiation_v1_oas3.json b/specs/sell_negotiation_v1_oas3.json
index 744600b9..7f74b53f 100644
--- a/specs/sell_negotiation_v1_oas3.json
+++ b/specs/sell_negotiation_v1_oas3.json
@@ -29,13 +29,13 @@
"tags": [
"offer"
],
- "description": "This method evaluates a seller's current listings and returns the set of IDs that are eligible for a seller-initiated discount offer to a buyer. A listing ID is returned only when one or more buyers have shown an "interest" in the listing. If any buyers have shown interest in a listing, the seller can initiate a "negotiation" with them by calling sendOfferToInterestedBuyers, which sends all interested buyers a message that offers the listing at a discount. For details about how to create seller offers to buyers, see Sending offers to buyers.",
+ "description": "This method evaluates a seller's current listings and returns the set of IDs that are eligible for a seller-initiated discount offer to a buyer.
A listing ID is returned only when one or more buyers have shown an \"interest\" in the listing.
If any buyers have shown interest in a listing, the seller can initiate a \"negotiation\" with them by calling sendOfferToInterestedBuyers, which sends all interested buyers a message that offers the listing at a discount.
For details about how to create seller offers to buyers, see Sending offers to buyers.",
"operationId": "findEligibleItems",
"parameters": [
{
"name": "limit",
"in": "query",
- "description": "This query parameter specifies the maximum number of items to return from the result set on a page in the paginated response. Minimum: 1 Maximum: 200 Default: 10",
+ "description": "This query parameter specifies the maximum number of items to return from the result set on a page in the paginated response.
Minimum: 1
Maximum: 200
Default: 10",
"required": false,
"schema": {
"type": "string"
@@ -44,7 +44,7 @@
{
"name": "offset",
"in": "query",
- "description": "This query parameter specifies the number of results to skip in the result set before returning the first result in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 results from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set. Default: 0",
+ "description": "This query parameter specifies the number of results to skip in the result set before returning the first result in the paginated response.
Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 results from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0",
"required": false,
"schema": {
"type": "string"
@@ -53,7 +53,7 @@
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
- "description": "The eBay marketplace on which you want to search for eligible listings. For a complete list of supported marketplaces, see Negotiation API requirements and restrictions.",
+ "description": "The eBay marketplace on which you want to search for eligible listings.
For a complete list of supported marketplaces, see Negotiation API requirements and restrictions.",
"required": true,
"schema": {
"type": "string"
@@ -129,13 +129,22 @@
"tags": [
"offer"
],
- "description": "This method sends eligible buyers offers to purchase items in a listing at a discount. When a buyer has shown interest in a listing, they become "eligible" to receive a seller-initiated offer to purchase the item(s). Sellers use findEligibleItems to get the set of listings that have interested buyers. If a listing has interested buyers, sellers can use this method (sendOfferToInterestedBuyers) to send an offer to the buyers who are interested in the listing. The offer gives buyers the ability to purchase the associated listings at a discounted price. For details about how to create seller offers to buyers, see Sending offers to buyers.",
+ "description": "This method sends eligible buyers offers to purchase items in a listing at a discount.
When a buyer has shown interest in a listing, they become \"eligible\" to receive a seller-initiated offer to purchase the item(s).
Sellers use findEligibleItems to get the set of listings that have interested buyers. If a listing has interested buyers, sellers can use this method (sendOfferToInterestedBuyers) to send an offer to the buyers who are interested in the listing. The offer gives buyers the ability to purchase the associated listings at a discounted price.
For details about how to create seller offers to buyers, see Sending offers to buyers.",
"operationId": "sendOfferToInterestedBuyers",
"parameters": [
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
- "description": "The eBay marketplace on which your listings with "eligible" buyers appear. For a complete list of supported marketplaces, see Negotiation API requirements and restrictions.",
+ "description": "The eBay marketplace on which your listings with \"eligible\" buyers appear.
For a complete list of supported marketplaces, see Negotiation API requirements and restrictions.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "Content-Type",
+ "in": "header",
+ "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
"required": true,
"schema": {
"type": "string"
@@ -334,11 +343,11 @@
"properties": {
"currency": {
"type": "string",
- "description": "The base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD. Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation"
+ "description": "The base currency applied to the value field to establish a monetary amount.
The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.
Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation"
},
"value": {
"type": "string",
- "description": "The monetary amount in the specified currency."
+ "description": "The monetary amount in the specified currency."
}
},
"description": "A complex type that describes the value of a monetary amount as represented by a global currency."
@@ -348,19 +357,19 @@
"properties": {
"allowCounterOffer": {
"type": "boolean",
- "description": "If set to true, the buyer is allowed to make a counter-offer to the seller's offer. Note: Currently, you must set this field to false; counter-offers are not supported in this release. Default: false"
+ "description": "If set to true, the buyer is allowed to make a counter-offer to the seller's offer.
Note: Currently, you must set this field to false; counter-offers are not supported in this release.
Default: false"
},
"message": {
"type": "string",
- "description": "A seller-defined message related to the offer being made. This message is sent to the list of "interested" buyers. To increase the conversion rate of the offers a seller makes to buyers, eBay recommends you always add a customized message to your offers. Maximum length: 2,000 characters"
+ "description": "A seller-defined message related to the offer being made.
This message is sent to the list of \"interested\" buyers.
To increase the conversion rate of the offers a seller makes to buyers, eBay recommends you always add a customized message to your offers.
Maximum length: 2,000 characters"
},
"offerDuration": {
- "description": "The length of time the offer is valid from when it is created. The duration of the offer begins at the date and time denoted by creationDate. When the span of time specified by offerDuration passes beyond the creationDate, the offer expires. Note: offerDuration currently defaults to 2 days and you cannot set it to any other value (if specified, the unit and value fields in TimeDuration must be set to DAY and 2, respectively). Default: 2 Days",
+ "description": "The length of time the offer is valid from when it is created.
The duration of the offer begins at the date and time denoted by creationDate. When the span of time specified by offerDuration passes beyond the creationDate, the offer expires.
Note: offerDuration currently defaults to 2 days and you cannot set it to any other value (if specified, the unit and value fields in TimeDuration must be set to DAY and 2, respectively).
Default: 2 Days",
"$ref": "#/components/schemas/TimeDuration"
},
"offeredItems": {
"type": "array",
- "description": "An array of objects where each object contains the details of an offer and the ID of the listing on which the offer is being made. Note that the service does not currently support the creation of multiple offers with a single call to sendOfferToInterestedBuyer. With this, each request can target only one listing at a time and you must populate this array with a single element that contains the details of one offer.",
+ "description": "An array of objects where each object contains the details of an offer and the ID of the listing on which the offer is being made.
Note that the service does not currently support the creation of multiple offers with a single call to sendOfferToInterestedBuyer. With this, each request can target only one listing at a time and you must populate this array with a single element that contains the details of one offer.",
"items": {
"$ref": "#/components/schemas/OfferedItem"
}
@@ -373,10 +382,10 @@
"properties": {
"listingId": {
"type": "string",
- "description": "The unique eBay-assigned ID for an eBay listing. A listingId is assigned by eBay when a seller creates a listing with the Trading API."
+ "description": "The unique eBay-assigned ID for an eBay listing.
A listingId is assigned by eBay when a seller creates a listing with the Trading API."
}
},
- "description": "A listing that is eligible for a seller-initiated offer to a buyer. Listings are identified by a listingId value that is generated and assigned by eBay when a seller lists an item using the Trading API. Note: The Negotiation API does not currently support listings that are managed with the Inventory API."
+ "description": "A listing that is eligible for a seller-initiated offer to a buyer.
Listings are identified by a listingId value that is generated and assigned by eBay when a seller lists an item using the Trading API.
Note: The Negotiation API does not currently support listings that are managed with the Inventory API."
},
"Error": {
"type": "object",
@@ -448,7 +457,7 @@
"properties": {
"allowCounterOffer": {
"type": "boolean",
- "description": "If set to true, the buyer is allowed to make a counter-offer to the seller's offer."
+ "description": "If set to true, the buyer is allowed to make a counter-offer to the seller's offer."
},
"buyer": {
"description": "The buyer who has been sent the offer.",
@@ -456,27 +465,27 @@
},
"creationDate": {
"type": "string",
- "description": "The date and time when the seller's offer was created. The returned timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z Example: 2018-08-20T07:09:00.000Z"
+ "description": "The date and time when the seller's offer was created.
The returned timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.
Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2018-08-20T07:09:00.000Z"
},
"initiatedBy": {
"type": "string",
- "description": "The eBay UserName of the user (seller) who initiated the offer."
+ "description": "The eBay UserName of the user (seller) who initiated the offer."
},
"lastModifiedDate": {
"type": "string",
- "description": "The date and time when the offer was last modified. The returned timestamp is formatted as an ISO 8601 string."
+ "description": "The date and time when the offer was last modified.
The returned timestamp is formatted as an ISO 8601 string."
},
"message": {
"type": "string",
- "description": "A seller-defined message related to the offer being made. This message is sent to the list of "interested" buyers along with the offer message from eBay."
+ "description": "A seller-defined message related to the offer being made. This message is sent to the list of \"interested\" buyers along with the offer message from eBay."
},
"offerDuration": {
- "description": "The length of time that the offer is valid. The duration of the offer begins at the date and time denoted by creationDate. When the span of time specified by offerDuration passes beyond the creationDate, the offer expires.",
+ "description": "The length of time that the offer is valid.
The duration of the offer begins at the date and time denoted by creationDate. When the span of time specified by offerDuration passes beyond the creationDate, the offer expires.",
"$ref": "#/components/schemas/TimeDuration"
},
"offeredItems": {
"type": "array",
- "description": "The list of items associated with the offer. Currently, the offer list is restricted to a single offer.",
+ "description": "The list of items associated with the offer.
Currently, the offer list is restricted to a single offer.",
"items": {
"$ref": "#/components/schemas/OfferedItem"
}
@@ -487,7 +496,7 @@
},
"offerStatus": {
"type": "string",
- "description": "The current state, or status, of an offer. Status states include PENDING, COUNTERED, ACCEPTED, and DECLINED. For implementation help, refer to eBay API documentation"
+ "description": "The current state, or status, of an offer.
Status states include PENDING, COUNTERED, ACCEPTED, and DECLINED. For implementation help, refer to eBay API documentation"
},
"offerType": {
"type": "string",
@@ -505,30 +514,30 @@
"properties": {
"discountPercentage": {
"type": "string",
- "description": "This value denotes the percentage that the listing in the offer will be discounted from its original listed price. The seller can specify either the exact price of the discounted items with the price field or they can use this field to specify the percentage that the listing will be discounted, but not both. Minimum: 5 Required if you do not specify a price value."
+ "description": "This value denotes the percentage that the listing in the offer will be discounted from its original listed price.
The seller can specify either the exact price of the discounted items with the price field or they can use this field to specify the percentage that the listing will be discounted, but not both.
Minimum: 5
Required if you do not specify a price value."
},
"listingId": {
"type": "string",
- "description": "This value is a unique eBay-assigned ID that identifies the listing to which the offer pertains. A listingId value is generated by eBay when you list an item with the Trading API."
+ "description": "This value is a unique eBay-assigned ID that identifies the listing to which the offer pertains.
A listingId value is generated by eBay when you list an item with the Trading API."
},
"price": {
- "description": "This value denotes the final discounted price of the listing in the offer being made to the buyer. This value must be lower than the original price of the item as stated in the original listing. The seller can use either this field to specify the exact discounted price of the listing or they can use the discountPercentage field to specify the percentage that the listing will be discounted, but not both. Required if you do not specify a discountPercentage value.",
+ "description": "This value denotes the final discounted price of the listing in the offer being made to the buyer. This value must be lower than the original price of the item as stated in the original listing.
The seller can use either this field to specify the exact discounted price of the listing or they can use the discountPercentage field to specify the percentage that the listing will be discounted, but not both.
Required if you do not specify a discountPercentage value.",
"$ref": "#/components/schemas/Amount"
},
"quantity": {
"type": "integer",
- "description": "This integer value indicates the number of items in the eBay listing for which the offer is being made. The offer being made by the seller is an "all or nothing" offer, meaning the buyer must purchase the indicated quantity of items in order to receive the discount on the transaction. Default: 1",
+ "description": "This integer value indicates the number of items in the eBay listing for which the offer is being made.
The offer being made by the seller is an \"all or nothing\" offer, meaning the buyer must purchase the indicated quantity of items in order to receive the discount on the transaction.
Default: 1",
"format": "int32"
}
},
- "description": "A complex type that defines the offer being made to an "interested" buyer."
+ "description": "A complex type that defines the offer being made to an \"interested\" buyer."
},
"PagedEligibleItemCollection": {
"type": "object",
"properties": {
"eligibleItems": {
"type": "array",
- "description": "A list of items that are eligible for a seller-initiated offer to a buyer. Each element in the list contains the listing ID of a listed item. These IDs represent the listings for which buyers have shown an interest.",
+ "description": "A list of items that are eligible for a seller-initiated offer to a buyer.
Each element in the list contains the listing ID of a listed item. These IDs represent the listings for which buyers have shown an interest.",
"items": {
"$ref": "#/components/schemas/EligibleItem"
}
@@ -539,25 +548,25 @@
},
"limit": {
"type": "integer",
- "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
+ "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
"format": "int32"
},
"next": {
"type": "string",
- "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set. Max length: 2048"
+ "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
},
"offset": {
"type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
"format": "int32"
},
"prev": {
"type": "string",
- "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set. Max length: 2048"
+ "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
},
"total": {
"type": "integer",
- "description": "The total number of items retrieved in the result set. If no items match the search criteria, the server returns the HTTP status code 204 No Content.",
+ "description": "The total number of items retrieved in the result set.
If no items match the search criteria, the server returns the HTTP status code
204 No Content.",
"format": "int32"
}
},
@@ -568,24 +577,24 @@
"properties": {
"offers": {
"type": "array",
- "description": "The offers container returns a list of the offers sent to buyers who have shown an interest in listings included in the offer.",
+ "description": "The offers container returns a list of the offers sent to buyers who have shown an interest in listings included in the offer.",
"items": {
"$ref": "#/components/schemas/Offer"
}
}
},
- "description": "The response object returned from a SendOfferToInterestedBuyers request."
+ "description": "The response object returned from a SendOfferToInterestedBuyers request."
},
"TimeDuration": {
"type": "object",
"properties": {
"unit": {
"type": "string",
- "description": "A time-measurement unit that specifies a singular period of time. A span of time is defined when you apply the value specified in the value field to the value specified for unit. Time-measurement units can be YEAR, MONTH, DAY, and so on. See TimeDurationUnitEnum for a complete list of possible time-measurement units. For implementation help, refer to eBay API documentation"
+ "description": "A time-measurement unit that specifies a singular period of time.
A span of time is defined when you apply the value specified in the value field to the value specified for unit.
Time-measurement units can be YEAR, MONTH, DAY, and so on. See TimeDurationUnitEnum for a complete list of possible time-measurement units. For implementation help, refer to eBay API documentation"
},
"value": {
"type": "integer",
- "description": "An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.",
+ "description": "An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.",
"format": "int32"
}
},
@@ -596,10 +605,10 @@
"properties": {
"maskedUsername": {
"type": "string",
- "description": "The masked user name is a user name that has certain characters hidden for privacy of the user."
+ "description": "The masked user name is a user name that has certain characters hidden for privacy of the user."
}
},
- "description": "This complex type identifies an eBay user."
+ "description": "This complex type identifies an eBay user."
}
},
"securitySchemes": {
diff --git a/specs/sell_recommendation_v1_oas3.json b/specs/sell_recommendation_v1_oas3.json
index 69a6a42f..130b26e0 100644
--- a/specs/sell_recommendation_v1_oas3.json
+++ b/specs/sell_recommendation_v1_oas3.json
@@ -10,7 +10,7 @@
"name": "eBay API License Agreement",
"url": "https://go.developer.ebay.com/api-license-agreement"
},
- "version": "1.1.0"
+ "version": "v1.1.0"
},
"servers": [
{
@@ -29,13 +29,13 @@
"tags": [
"listing_recommendation"
],
- "description": "The find method currently returns information for a single recommendation type (AD) which contains information that sellers can use to configure Promoted Listings ad campaigns. The response from this method includes an array of the seller's listing IDs, where each element in the array contains recommendations related to the associated listing ID. For details on how to use this method, see Using the Recommendation API to help configure campaigns. The AD recommendation type The AD type contains two sets of information: The promoteWithAd indicator The promoteWithAd response field indicates whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign. The returned value is set to either RECOMMENDED or UNDETERMINED, where RECOMMENDED identifies the listings that will benefit the most from having them included in an ad campaign. The bid percentage Also known as the "ad rate," the bidPercentage field provides the current trending bid percentage of similarly promoted items in the marketplace. The ad rate is a user-specified value that indicates the level of promotion that eBay applies to the campaign across the marketplace. The value is also used to calculate the Promotion Listings fee, which is assessed to the seller if a Promoted Listings action results in the sale of an item. Configuring the request You can configure a request to review all of a seller's currently active listings, or just a subset of them. All active listings – If you leave the request body empty, the request targets all the items currently listed by the seller. Here, the response is filtered to contain only the items where promoteWithAd equals RECOMMENDED. In this case, eBay recommends that all the returned listings should be included in a Promoted Listings ad campaign. Selected listing IDs – If you populate the request body with a set of listingIds, the response contains data for all the specified listing IDs. In this scenario, the response provides you with information on listings where the promoteWithAd can be either RECOMMENDED or UNDETERMINED. The paginated response Because the response can contain many listing IDs, the findListingRecommendations method paginates the response set. You can control size of the returned pages, as well as an offset that dictates where to start the pagination, using query parameters in the request.",
+ "description": "The find method currently returns information for a single recommendation type (AD) which contains information that sellers can use to configure Promoted Listings ad campaigns. The response from this method includes an array of the seller's listing IDs, where each element in the array contains recommendations related to the associated listing ID. For details on how to use this method, see Using the Recommendation API to help configure campaigns.
The AD recommendation type
The AD type contains two sets of information:
- The promoteWithAd indicator
The promoteWithAd response field indicates whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign. The returned value is set to either RECOMMENDED or UNDETERMINED, where RECOMMENDED identifies the listings that will benefit the most from having them included in an ad campaign.
- The bid percentage
Also known as the \"ad rate,\" the bidPercentage field provides the current trending bid percentage of similarly promoted items in the marketplace. The ad rate is a user-specified value that indicates the level of promotion that eBay applies to the campaign across the marketplace. The value is also used to calculate the Promotion Listings fee, which is assessed to the seller if a Promoted Listings action results in the sale of an item.
Configuring the request
You can configure a request to review all of a seller's currently active listings, or just a subset of them.
- All active listings – If you leave the request body empty, the request targets all the items currently listed by the seller.
Here, the response is filtered to contain only the items where promoteWithAd equals RECOMMENDED. In this case, eBay recommends that all the returned listings should be included in a Promoted Listings ad campaign.
- Selected listing IDs – If you populate the request body with a set of listingIds, the response contains data for all the specified listing IDs.
In this scenario, the response provides you with information on listings where the promoteWithAd can be either RECOMMENDED or UNDETERMINED.
The paginated response
Because the response can contain many listing IDs, the findListingRecommendations method paginates the response set.
You can control size of the returned pages, as well as an offset that dictates where to start the pagination, using query parameters in the request.",
"operationId": "findListingRecommendations",
"parameters": [
{
"name": "filter",
"in": "query",
- "description": "Provide a list of key-value pairs to specify the criteria you want to use to filter the response. In the list, separate each filter key from its associated value with a colon (":"). Currently, the only supported filter value is recommendationTypes and it supports only the ("AD") type. Follow the recommendationTypes specifier with the filter type(s) enclosed in curly braces ("{ }"), and separate multiple types with commas. Example: filter=recommendationTypes:{AD} Default: recommendationTypes:{AD}",
+ "description": "Provide a list of key-value pairs to specify the criteria you want to use to filter the response.
In the list, separate each filter key from its associated value with a colon (\":\").
Currently, the only supported filter value is recommendationTypes and it supports only the (\"AD\") type. Follow the recommendationTypes specifier with the filter type(s) enclosed in curly braces (\"{ }\"), and separate multiple types with commas.
Example: filter=recommendationTypes:{AD}
Default: recommendationTypes:{AD}",
"required": false,
"schema": {
"type": "string"
@@ -44,7 +44,7 @@
{
"name": "limit",
"in": "query",
- "description": "Use this query parameter to set the maximum number of ads to return on a page from the paginated response. Default: 10 Maximum: 500",
+ "description": "Use this query parameter to set the maximum number of ads to return on a page from the paginated response.
Default: 10
Maximum: 500",
"required": false,
"schema": {
"type": "string"
@@ -53,7 +53,7 @@
{
"name": "offset",
"in": "query",
- "description": "Specifies the number of ads to skip in the result set before returning the first ad in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set. Default: 0",
+ "description": "Specifies the number of ads to skip in the result set before returning the first ad in the paginated response.
Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
",
"required": false,
"schema": {
"type": "string"
@@ -62,7 +62,7 @@
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
- "description": "Use this header to specify the eBay marketplace where you list the items for which you want to get recommendations.",
+ "description": "This header specifies the eBay marketplace where you list the items for which you want to get recommendations.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
"required": true,
"schema": {
"type": "string"
@@ -160,14 +160,14 @@
"properties": {
"bidPercentages": {
"type": "array",
- "description": "This field returns information that you can use to configure the bidPercentage field in a Promoted Listings campaign. Note: Currently, ITEM and TRENDING are the only supported bid percentage types. The ITEM suggested bid percentages are tailored to each of your items and are designed to help you stay competitive while finding an optimal balance between performance and cost. The recommendations are calculated based on a variety of factors that may include item attributes, seasonality, past performance, and current competition for each of your listings. The TRENDING suggested bid percentages are calculated by reviewing the category level average ad rates in the marketplace. Setting the bidPercentage of your ad campaign based on these rate recommendations will help the items in the campaign be competitive with other items in the marketplace by improving their chances of being displayed more often in the marketplace.",
+ "description": "This field returns information that you can use to configure the bidPercentage field in a Promoted Listings campaign.
Note: Currently, ITEM and TRENDING are the only supported bid percentage types.
The ITEM suggested bid percentages are tailored to each of your items and are designed to help you stay competitive while finding an optimal balance between performance and cost. The recommendations are calculated based on a variety of factors that may include item attributes, seasonality, past performance, and current competition for each of your listings.
The TRENDING suggested bid percentages are calculated by reviewing the category level average ad rates in the marketplace.
Setting the bidPercentage of your ad campaign based on these rate recommendations will help the items in the campaign be competitive with other items in the marketplace by improving their chances of being displayed more often in the marketplace.",
"items": {
"$ref": "#/components/schemas/BidPercentages"
}
},
"promoteWithAd": {
"type": "string",
- "description": "An enum whose values describe whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign. IDs deemed RECOMMENDED by eBay are the listings with the highest potential of benefiting from being promoted. The recommendation calculation is based on marketplace trends, like buyer demand and the competition in the item’s category. Note: A promoteWithAd value cannot be calculated for listings that are part of Promoted Listings campaigns. Because of this, if you call findListingRecommendations with a specific set of listing IDs, the promoteWithAd field is not returned for any of the listings that are involved in a promotion. However, as long as they are eligible, the trending bidPercentage is returned for all specified listings, even if they are part of an ad campaign. For implementation help, refer to eBay API documentation"
+ "description": "An enum whose values describe whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign.
IDs deemed RECOMMENDED by eBay are the listings with the highest potential of benefiting from being promoted. The recommendation calculation is based on marketplace trends, like buyer demand and the competition in the itemās category. Note: A promoteWithAd value cannot be calculated for listings that are part of Promoted Listings campaigns.
Because of this, if you call findListingRecommendations with a specific set of listing IDs, the promoteWithAd field is not returned for any of the listings that are involved in a promotion. However, as long as they are eligible, the trending bidPercentage is returned for all specified listings, even if they are part of an ad campaign.
For implementation help, refer to eBay API documentation"
}
},
"description": "A complex type that contains recommendations and information on how to configure Promoted Listings ad campaigns."
@@ -177,11 +177,11 @@
"properties": {
"basis": {
"type": "string",
- "description": "The basis by which the ad rate is calculated. Valid Values: ITEM and TRENDING For implementation help, refer to eBay API documentation"
+ "description": "The basis by which the ad rate is calculated.
Valid Values: ITEM and TRENDING For implementation help, refer to eBay API documentation"
},
"value": {
"type": "string",
- "description": "The bid percentage data is a single precision value, as calculated by the associated basis. In Promoted listings ad campaigns, the bid percentage (also known as the ad rate) is a user-defined value that sets the level that eBay raises the visibility of the listing in the marketplace. It is also the rate that is used to calculate the Promoted Listings fee. Minimum value: 1.0 Maximum value: 100.0"
+ "description": "The bid percentage data is a single precision value, as calculated by the associated basis. In Promoted listings ad campaigns, the bid percentage (also known as the ad rate) is a user-defined value that sets the level that eBay raises the visibility of the listing in the marketplace. It is also the rate that is used to calculate the Promoted Listings fee.
Minimum value: 1.0 Maximum value: 100.0
"
}
},
"description": "A complex type that returns data related to Promoted Listings bid percentages."
@@ -256,7 +256,7 @@
"properties": {
"listingIds": {
"type": "array",
- "description": "A comma-separated list of listing IDs for which you want Promoted Listings ad configuration information. Currently, this method accepts only listingId values from the Trading API. Max: 500 listing IDs",
+ "description": "A comma-separated list of listing IDs for which you want Promoted Listings ad configuration information. Currently, this method accepts only listingId values from the Trading API.
Max: 500 listing IDs
",
"items": {
"type": "string"
}
@@ -272,7 +272,7 @@
"description": "An ID that identifies the active listing associated with the eBay recommendations."
},
"marketing": {
- "description": "This return object provides the eBay recommendations and information related to the associated listing ID. The container currently returns the AD recommendation type, which contains information that sellers can use to configure Promoted Listings ad campaigns. This container is returned with each ListingRecommendation object, except when: The listing ID is not eligible for Promoted Listings The listing ID is currently in a Promoted Listings campaign The listing ID is invalid",
+ "description": "This return object provides the eBay recommendations and information related to the associated listing ID.
The container currently returns the AD recommendation type, which contains information that sellers can use to configure Promoted Listings ad campaigns.
This container is returned with each ListingRecommendation object, except when: - The listing ID is not eligible for Promoted Listings
- The listing ID is currently in a Promoted Listings campaign
- The listing ID is invalid
",
"$ref": "#/components/schemas/MarketingRecommendation"
}
},
@@ -290,7 +290,7 @@
"description": "A message that can conditionally accompany the listing information."
}
},
- "description": "A complex type that contains information about how a seller can improve their listing configurations. The AD object contains Promoted Listings recommendations and information, which the seller can use to improve buyer conversions. The response can also contain an optional message about the returned data."
+ "description": "A complex type that contains information about how a seller can improve their listing configurations. The AD object contains Promoted Listings recommendations and information, which the seller can use to improve buyer conversions. The response can also contain an optional message about the returned data."
},
"PagedListingRecommendationCollection": {
"type": "object",
@@ -301,32 +301,32 @@
},
"limit": {
"type": "integer",
- "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
+ "description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
"format": "int32"
},
"listingRecommendations": {
"type": "array",
- "description": "Returns a list of listingRecommendations, where each element in the list offers recommendations for the associated listingId. Which elements are returned depend on how you structure the request. For example, if you request recommendations for all of a sellers listings (by leaving the request payload empty), ad recommendations are returned only for those listings where promoteWithAd is set to RECOMMENDED.",
+ "description": "Returns a list of listingRecommendations, where each element in the list offers recommendations for the associated listingId.
Which elements are returned depend on how you structure the request. For example, if you request recommendations for all of a sellers listings (by leaving the request payload empty), ad recommendations are returned only for those listings where promoteWithAd is set to RECOMMENDED.",
"items": {
"$ref": "#/components/schemas/ListingRecommendation"
}
},
"next": {
"type": "string",
- "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set. Max length: 2048"
+ "description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
},
"offset": {
"type": "integer",
- "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.",
+ "description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
"format": "int32"
},
"prev": {
"type": "string",
- "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set. Max length: 2048"
+ "description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
},
"total": {
"type": "integer",
- "description": "The total number of items retrieved in the result set. If no items are found, this field is returned with a value of 0.",
+ "description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
"format": "int32"
}
},
diff --git a/specs/sell_stores_v1_oas3.json b/specs/sell_stores_v1_oas3.json
new file mode 100644
index 00000000..d9ae1709
--- /dev/null
+++ b/specs/sell_stores_v1_oas3.json
@@ -0,0 +1,905 @@
+{
+ "openapi": "3.0.0",
+ "info": {
+ "title": "Store API",
+ "description": "This API provides stores-related resources for third-party developers. These resources let you retrieve basic store information such as store name, description, store url, return store category hierarchy, add,rename,move,delete a single user's eBay store category, and retrieve the processing status of these tasks.
The stores resource methods require an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application)
",
+ "contact": {
+ "name": "eBay Inc,"
+ },
+ "license": {
+ "name": "eBay API License Agreement",
+ "url": "https://go.developer.ebay.com/api-license-agreement"
+ },
+ "version": "1"
+ },
+ "servers": [
+ {
+ "url": "https://api.ebay.com{basePath}",
+ "description": "Production",
+ "variables": {
+ "basePath": {
+ "default": "/sell/stores/v1"
+ }
+ }
+ }
+ ],
+ "paths": {
+ "/store/categories": {
+ "get": {
+ "tags": [
+ "store"
+ ],
+ "description": "This method is used to retrieve the category hierarchy for an eBay user's store.
Note: Three levels of store categories are supported.",
+ "operationId": "getStoreCategories",
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetStoreCategoriesResponseType"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "225002": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "User must have an active store subscription."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "225000": {
+ "domain": "API_STORES",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.stores"
+ ]
+ }
+ ]
+ },
+ "post": {
+ "tags": [
+ "store"
+ ],
+ "description": "This method is used to add a single new custom category to a user's eBay store through an asynchronous request. A successful call returns the getStoreTask URI in the Location response header. Call getStoreTask (or getStoreTasks) method to retrieve the status of the add category operation.
Note: Three levels of store categories are supported.
Important! If you initiate a category change, you cannot make additional category changes until the previous change request has completed. Use getStoreTask (or getStoreTasks) method to get latest status of your last request.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This call is used to add single new category of a user's eBay store.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This call is used to add single new category of a user's eBay store.",
+ "$ref": "#/components/schemas/AddStoreCategoryRequestType"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "202": {
+ "description": "The request is accepted, user should get the location url in response to retrieve async task status."
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "225001": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Input data for {param} is invalid or missing. Please check API documentation."
+ },
+ "225002": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "The user must have an active store subscription."
+ },
+ "225003": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "You cannot make additional category changes until your previous change request has completed. Use getStoreTask method to get latest status of your last request."
+ },
+ "226000": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "You cannot have duplicate category names under the same category parent."
+ },
+ "226001": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Invalid characters found in {category_name}. Please see documentation for more information on recommended valid characters."
+ },
+ "226002": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Category name can not be empty, or 'Other'."
+ },
+ "226003": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Category name {category_name} exceeds the maximum allowed length of {max_length} characters."
+ },
+ "226004": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Custom store category count exceeds the maximum allowed count {max_count}."
+ },
+ "226005": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Custom store category {category_name} exceeds the maximum allowed category depth {depth_limit}."
+ },
+ "226006": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Category id {category_id} doesn't exist for the store."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "225000": {
+ "domain": "API_STORES",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.stores"
+ ]
+ }
+ ]
+ }
+ },
+ "/store/categories/{category_id}": {
+ "put": {
+ "tags": [
+ "store"
+ ],
+ "description": "This method is used to rename the single category of a user's eBay store through an asynchronous request. A successful call returns the getStoreTask URI in the Location response header. The user calls getStoreTask to retrieve the status of the rename category operation.
Important! If you initiate a category change, you cannot make additional category changes until the previous change request has completed. Use getStoreTask (or getStoreTasks) method to get latest status of your last request.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This call is used to rename the single category of a user's eBay store.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This call is used to rename the single category of a user's eBay store.",
+ "$ref": "#/components/schemas/RenameStoreCategoryRequestType"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "204": {
+ "description": "No Content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "225001": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Input data for {param} is invalid or missing. Please check API documentation."
+ },
+ "225002": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "The user must have an active store subscription."
+ },
+ "226000": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "You cannot have duplicate category names under the same category parent."
+ },
+ "226001": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Invalid characters found in {category_name}. Please see documentation for more information on recommended valid characters."
+ },
+ "226002": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Category name can not be empty, or 'Other'."
+ },
+ "226003": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Category name {category_name} exceeds the maximum allowed length of {max_length} characters."
+ },
+ "226006": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Category id {category_id} doesn't exist for the store."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "225000": {
+ "domain": "API_STORES",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.stores"
+ ]
+ }
+ ]
+ },
+ "delete": {
+ "tags": [
+ "store"
+ ],
+ "description": "This method is used to delete one custom category of a user's eBay store through an asynchronous request. A successful call returns the getStoreTask URI in the Location response header. Call getStoreTask (or getStoreTasks) method to retrieve the status of the delete category operation.
Important! If you initiate a category change, you cannot make additional category changes until the previous change request has completed. Use getStoreTask (or getStoreTasks) method to get latest status of your last request.
The getStoreCategories method can be used to retrieve store category IDs.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This call is used to delete one category of a user's eBay store.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This call is used to delete one category of a user's eBay store.",
+ "$ref": "#/components/schemas/DeleteStoreCategoryRequestType"
+ }
+ }
+ },
+ "required": false
+ },
+ "responses": {
+ "202": {
+ "description": "The request is accepted, user should get the location url in response to retrieve async task status."
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "225001": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Input data for {param} is invalid or missing. Please check API documentation."
+ },
+ "225002": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "The user must have an active store subscription."
+ },
+ "225003": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "You cannot make additional category changes until your previous change request has completed. Use getStoreTask method to get latest status of your last request."
+ },
+ "226006": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Category id {category_id} doesn't exist for the store."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "225000": {
+ "domain": "API_STORES",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.stores"
+ ]
+ }
+ ]
+ }
+ },
+ "/store": {
+ "get": {
+ "tags": [
+ "store"
+ ],
+ "description": "This method is used to retrieve information for an eBay user's store such as store name, store URL, and description.",
+ "operationId": "getStore",
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetStoreResponseType"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "225002": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "User must have an active store subscription."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "225000": {
+ "domain": "API_STORES",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.stores"
+ ]
+ }
+ ]
+ }
+ },
+ "/store/tasks/{task_id}": {
+ "get": {
+ "tags": [
+ "store"
+ ],
+ "description": "This method retrieves the current status of a recent store operation. The unique identifier of the task is passed in as a path parameter.",
+ "operationId": "getStoreTask",
+ "parameters": [
+ {
+ "name": "task_id",
+ "in": "path",
+ "description": "The unique identifier of an eBay Store async task. A taskId value is returned in the response of other successful calls. (e.g.addStoreCategory, moveStoreCategory, deleteStoreCategory).",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetStoreTaskResponseType"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "225001": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Input data for {param} is invalid or missing. Please check API documentation."
+ },
+ "225002": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "The user must have an active store subscription."
+ },
+ "226100": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "The provided task_id could not be matched to a store category request for the store."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "225000": {
+ "domain": "API_STORES",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.stores"
+ ]
+ }
+ ]
+ }
+ },
+ "/store/tasks": {
+ "get": {
+ "tags": [
+ "store"
+ ],
+ "description": "This method retrieves the status of all async store tasks for a store. Every task is set as FAILED or COMPLETED once it's execution time reaches 24 hours.",
+ "operationId": "getStoreTasks",
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetStoreTasksResponseType"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "225002": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "The user must have an active store subscription."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "225000": {
+ "domain": "API_STORES",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.stores"
+ ]
+ }
+ ]
+ }
+ },
+ "/store/categories/move_category": {
+ "post": {
+ "tags": [
+ "store"
+ ],
+ "description": "This method is used to move an existing user's eBay store custom category through an asynchronous request. A successful call returns the getStoreTask URI in the Location response header. The user calls getStoreTask to retrieve the status of the move category operation.
Important! If you initiate a category change, you cannot make additional category changes until the previous change request has completed. Use getStoreTask (or getStoreTasks) method to get latest status of your last request.
For more information, refer to HTTP request headers.",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "description": "This method is used to move one category of a user's eBay store. This operation is an asynchronous request. A successful call returns the getStoreTask URI in the Location response header. The user calls getStoreTask to retrieve the status of the add category operation.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "This method is used to move one category of a user's eBay store. This operation is an asynchronous request. A successful call returns the getStoreTask URI in the Location response header. The user calls getStoreTask to retrieve the status of the add category operation.",
+ "$ref": "#/components/schemas/MoveStoreCategoryRequestType"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "202": {
+ "description": "The request is accepted, user should get the location url in response to retrieve async task status."
+ },
+ "400": {
+ "description": "Bad Request",
+ "x-response-codes": {
+ "errors": {
+ "225001": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Input data for {param} is invalid or missing. Please check API documentation."
+ },
+ "225002": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "The user must have an active store subscription."
+ },
+ "225003": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "You cannot make additional category changes until your previous change request has completed. Use getStoreTask method to get latest status of your last request."
+ },
+ "226000": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "You cannot have duplicate category names under the same category parent."
+ },
+ "226005": {
+ "domain": "API_STORES",
+ "category": "REQUEST",
+ "description": "Custom store category {category_name} exceeds the maximum allowed category depth {depth_limit}."
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "x-response-codes": {
+ "errors": {
+ "225000": {
+ "domain": "API_STORES",
+ "category": "APPLICATION",
+ "description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
+ }
+ }
+ }
+ }
+ },
+ "security": [
+ {
+ "api_auth": [
+ "https://api.ebay.com/oauth/api_scope/sell.stores"
+ ]
+ }
+ ]
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "AddStoreCategoryRequestType": {
+ "type": "object",
+ "properties": {
+ "categoryName": {
+ "type": "string",
+ "description": "The seller-specified name of the custom category.
Max Length: 35"
+ },
+ "destinationParentCategoryId": {
+ "type": "string",
+ "description": "This field is used to specify the parent category to which the new category belongs. To specify the new category as a top-level category, set the value of this field to -999, or just omit this field, as the default value is -999.
The getStoreCategories method can be used to retrieve store category IDs.
Default: ROOT category ID(-999) if it's null."
+ },
+ "listingDestinationCategoryId": {
+ "type": "string",
+ "description": "If the store category specified as the destinationParentCategoryId is a leaf category with active listings, those listings are moved to the store category identified through this listingDestinationCategoryId. If this field is omitted, the new store category being added under the parent category inherits those listings.
The getStoreCategories method can be used to retrieve store category IDs.
Default: Newly added category ID if it's null."
+ }
+ },
+ "description": "The base request type of the addStoreCategory method. It is used to provide the name and location for the new category."
+ },
+ "DeleteStoreCategoryRequestType": {
+ "type": "object",
+ "properties": {
+ "listingDestinationCategoryId": {
+ "type": "string",
+ "description": "This field is only needed if the category to be deleted or any of its children categories have one or more active listings. The operation will fail otherwise. All active listings in or under the category to be deleted will be moved to the store category specified in this field.
The getStoreCategories method can be used to retrieve store category IDs.
Default: OTHER category ID (1) if it's null."
+ }
+ },
+ "description": "The base request type of the deleteStoreCategory method. It is used to provide a new category home for the listings that are currently in the store category to be deleted."
+ },
+ "Error": {
+ "type": "object",
+ "properties": {
+ "category": {
+ "type": "string",
+ "description": "Identifies the type of erro."
+ },
+ "domain": {
+ "type": "string",
+ "description": "Name for the primary system where the error occurred. This is relevant for application errors."
+ },
+ "errorId": {
+ "type": "integer",
+ "description": "A unique number to identify the error.",
+ "format": "int32"
+ },
+ "inputRefIds": {
+ "type": "array",
+ "description": "An array of request elements most closely associated to the error.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "longMessage": {
+ "type": "string",
+ "description": "A more detailed explanation of the error."
+ },
+ "message": {
+ "type": "string",
+ "description": "Information on how to correct the problem, in the end user's terms and language where applicable."
+ },
+ "outputRefIds": {
+ "type": "array",
+ "description": "An array of request elements most closely associated to the error.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "parameters": {
+ "type": "array",
+ "description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.",
+ "items": {
+ "$ref": "#/components/schemas/ErrorParameter"
+ }
+ },
+ "subdomain": {
+ "type": "string",
+ "description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc."
+ }
+ },
+ "description": "This type defines the fields that can be returned in an error."
+ },
+ "ErrorParameter": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "The object of the error."
+ },
+ "value": {
+ "type": "string",
+ "description": "The value of the object."
+ }
+ }
+ },
+ "GetStoreCategoriesResponseType": {
+ "type": "object",
+ "properties": {
+ "storeCategories": {
+ "type": "array",
+ "description": "An array of top-level categories defined for the eBay store. A childrenCategories array is used for second and third-level categories, if defined for the store.",
+ "items": {
+ "$ref": "#/components/schemas/StoreCategoryType"
+ }
+ }
+ },
+ "description": "The base response type of the getStoreCategories method. This type provides the entire category hierarchy for the store."
+ },
+ "GetStoreResponseType": {
+ "type": "object",
+ "properties": {
+ "description": {
+ "type": "string",
+ "description": "The seller-provided description of the eBay Store.
Max length: 300"
+ },
+ "lastOpenedTime": {
+ "type": "string",
+ "description": "Indicates the time the store was last opened or reopened."
+ },
+ "logo": {
+ "description": "This container provides information about a Store logo.",
+ "$ref": "#/components/schemas/StoreLogoType"
+ },
+ "name": {
+ "type": "string",
+ "description": "The name of the eBay Store. The name is shown at the top of the Store page.
Max length: 35"
+ },
+ "url": {
+ "type": "string",
+ "description": "The complete URL of the user's store."
+ },
+ "urlPath": {
+ "type": "string",
+ "description": "The relative URL path of the Store.
Max length: 58"
+ }
+ },
+ "description": "The base response type of the getStore method. It is used to describe a seller's eBay store, and includes the eBay Store name, the description of the store, the URL to the eBay Store."
+ },
+ "GetStoreTaskResponseType": {
+ "type": "object",
+ "properties": {
+ "task": {
+ "description": "This container provides detailed information about the status of the store task.",
+ "$ref": "#/components/schemas/StoreTaskType"
+ }
+ },
+ "description": "The base response type of the getStoreTask method."
+ },
+ "GetStoreTasksResponseType": {
+ "type": "object",
+ "properties": {
+ "task": {
+ "type": "array",
+ "description": "This array provides detailed information about the status of one or more store tasks.",
+ "items": {
+ "$ref": "#/components/schemas/StoreTaskType"
+ }
+ }
+ },
+ "description": "The base response type of the getStoreTasks method."
+ },
+ "MoveStoreCategoryRequestType": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "The unique identifier of an eBay Store's custom category. eBay auto-generates this identifier when a seller establishes a custom store category. This category ID should not be confused with an eBay category ID. This is the category that is moved."
+ },
+ "destinationParentCategoryId": {
+ "type": "string",
+ "description": "The new parent category of the category to be moved is specified in this field. If the category is being moved to level 1 category, set this value to -999."
+ },
+ "listingDestinationCategoryId": {
+ "type": "string",
+ "description": "This field is only needed if the category to be moved is a leaf category with listings, but a category that becomes a non-leaf category after the move. The listings of the category to be moved are moved to the category specified in this field."
+ }
+ },
+ "description": "The base request type of the moveStoreCategory method. It is used to provide the name of the category to be moved and its new location."
+ },
+ "RenameStoreCategoryRequestType": {
+ "type": "object",
+ "properties": {
+ "categoryName": {
+ "type": "string",
+ "description": "The seller-specified name of the custom category. This is the new name of the category specified through path parameter.
Max Length: 35"
+ }
+ },
+ "description": "The base request type of the renameStoreCategory method. It is used to rename a customized eBay Store category."
+ },
+ "StoreCategoryType": {
+ "type": "object",
+ "properties": {
+ "categoryId": {
+ "type": "string",
+ "description": "Unique identifier of an eBay Store's custom category. eBay auto-generates this identifier when a seller establishes a custom store category. This category ID should not be confused with an eBay category ID."
+ },
+ "categoryName": {
+ "type": "string",
+ "description": "The seller-specified name of the custom category."
+ },
+ "childrenCategories": {
+ "type": "array",
+ "description": "This array is returned to show second and third-level store categories. eBay Stores support up to three category levels.",
+ "items": {
+ "$ref": "#/components/schemas/StoreCategoryType"
+ }
+ },
+ "level": {
+ "type": "integer",
+ "description": "The level indicates the category level of the category tree.
Note: Three levels of store categories are supported. All categories belonging to the same parent should have the same level.",
+ "format": "int32"
+ },
+ "order": {
+ "type": "integer",
+ "description": "The order in which the custom store category appears in the list of store categories when the eBay store is visited.",
+ "format": "int32"
+ }
+ },
+ "description": "This type is used to provide details about a customized eBay Store category."
+ },
+ "StoreLogoType": {
+ "type": "object",
+ "properties": {
+ "url": {
+ "type": "string",
+ "description": "The URL of the seller's store logo."
+ }
+ },
+ "description": "This type is used to provide url of the seller's store logo."
+ },
+ "StoreTaskType": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "The unique identifier of an eBay Store task."
+ },
+ "message": {
+ "type": "string",
+ "description": "This field provides a textual description on the status of the task, and could help user troubleshoot any issues if there is an issue with eBay creating the task."
+ },
+ "status": {
+ "type": "string",
+ "description": "The enumeration value here indicates the processing status of the task. See the StoreTaskStatusEnum type for more information on supported status values. For implementation help, refer to eBay API documentation"
+ },
+ "type": {
+ "type": "string",
+ "description": "The enumeration value indicates the task type. For implementation help, refer to eBay API documentation"
+ }
+ },
+ "description": "This type is used to provide details about the status of the Store Task."
+ }
+ },
+ "securitySchemes": {
+ "api_auth": {
+ "type": "oauth2",
+ "description": "The security definitions for this API. Please check individual operations for applicable scopes.",
+ "flows": {}
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/src/api/apiFactory.ts b/src/api/apiFactory.ts
index 66315e55..7a051e8a 100644
--- a/src/api/apiFactory.ts
+++ b/src/api/apiFactory.ts
@@ -1,4 +1,4 @@
-import {ClientAlerts, Finding, Merchandising, Shopping, Trading} from '../types/index.js';
+import {ClientAlerts, Merchandising, Shopping, Trading} from '../types/index.js';
import Api from './index.js';
import {
Browse,
@@ -29,7 +29,6 @@ import {
AccountV1,
AccountV2,
Analytics as SellAnalytics,
- Compliance,
Feed as SellFeed,
Finances,
Fulfillment,
@@ -40,7 +39,8 @@ import {
Metadata,
Negotiation,
Recommendation,
- Sell
+ Sell,
+ Stores
} from './restful/sell/index.js';
import Traditional from './traditional/index.js';
@@ -98,7 +98,6 @@ export default class ApiFactory extends Api {
account: this.createRestfulApi(AccountV1),
accountV2: this.createRestfulApi(AccountV2),
analytics: this.createRestfulApi(SellAnalytics),
- compliance: this.createRestfulApi(Compliance),
fulfillment: this.createRestfulApi(Fulfillment),
inventory: this.createRestfulApi(Inventory),
marketing: this.createRestfulApi(SellMarketing),
@@ -108,7 +107,8 @@ export default class ApiFactory extends Api {
feed: this.createRestfulApi(SellFeed),
logistics: this.createRestfulApi(Logistics),
negotiation: this.createRestfulApi(Negotiation),
- listing: this.createRestfulApi(Listing)
+ listing: this.createRestfulApi(Listing),
+ stores: this.createRestfulApi(Stores)
};
}
@@ -128,10 +128,6 @@ export default class ApiFactory extends Api {
return this.traditional.createShoppingApi();
}
- public createFindingApi(): Finding {
- return this.traditional.createFindingApi();
- }
-
public createClientAlertsApi(): ClientAlerts {
return this.traditional.createClientAlertsApi();
}
diff --git a/src/api/restful/buy/browse/index.ts b/src/api/restful/buy/browse/index.ts
index 87ed6c86..46bc96ff 100644
--- a/src/api/restful/buy/browse/index.ts
+++ b/src/api/restful/buy/browse/index.ts
@@ -1,13 +1,10 @@
import {
- AddCartItemInput,
BuyBrowseGetItemsParams,
BuyBrowseItemByLegacyIdParams,
BuyBrowseSearchByImageParams,
BuyBrowseSearchParams,
CompatibilityPayload,
- RemoveCartItemInput,
- SearchByImageRequest,
- UpdateCartItemInput
+ SearchByImageRequest
} from '../../../../types/index.js';
import {operations} from '../../../../types/restful/specs/buy_browse_v1_oas3.js';
import Restful, {OpenApi} from '../../index.js';
@@ -115,45 +112,4 @@ export default class Browse extends Restful implements OpenApi {
const id = encodeURIComponent(itemId);
return this.post(`/item/${id}/check_compatibility`, body);
}
-
- //
- // Shopping Cart
- //
-
- /**
- * This is an Experimental method. This method creates an eBay cart for the eBay member, if one does not exist, and
- * adds items to that cart.
- *
- * @param {Object} item AddCartItemInput
- */
- public addItem(item: AddCartItemInput) {
- return this.post('/shopping_cart/add_item', item);
- }
-
- /**
- * This is an experimental method. This method retrieves all the items in the eBay member's cart;
- * items added to the cart while on ebay.com as well as items added to the cart using the Browse API.
- */
- public getShoppingCart() {
- return this.get('/shopping_cart/');
- }
-
- /**
- * This is an experimental method. This method removes a specific item from the eBay member's cart.
- *
- * @param {Object} item RemoveCartItemInput
- */
- public removeItem(item: RemoveCartItemInput) {
- return this.post('/shopping_cart/remove_item', item);
- }
-
- /**
- * This is an experimental method. This method updates the quantity value of a specific item in the eBay member's
- * cart.
- *
- * @param {UpdateCartItemInput} item UpdateCartItemInput
- */
- public updateQuantity(item: UpdateCartItemInput) {
- return this.post('/shopping_cart/update_quantity', item);
- }
}
diff --git a/src/api/restful/buy/feed/index.ts b/src/api/restful/buy/feed/index.ts
index aafb59de..e0ab2304 100644
--- a/src/api/restful/buy/feed/index.ts
+++ b/src/api/restful/buy/feed/index.ts
@@ -66,19 +66,15 @@ export default class Feed extends Restful implements OpenApi {
}
/**
- * The Hourly Snapshot feed file is generated each hour every day for all categories.
+ * This method lets you download a TSV_GZIP (tab separated value gzip) Item Priority feed file.
*
* @param {BuyFeedParams} params
- * @param {String} snapshotDate
* @param range his header specifies the range in bytes of the chunks of the gzip file being returned.
* Format: bytes=startpos-endpos For example, the following retrieves the first 10 MBs of the feed file.
*/
- public getProductFeed(params: BuyFeedParams, snapshotDate: string, range: string) {
- return this.get('/product', {
- params: {
- ...params,
- snapshot_date: snapshotDate
- },
+ public getItemPriorityFeed(params: BuyFeedParams, range: string) {
+ return this.get('/item_priority', {
+ params,
headers: {
'Range': range
}
diff --git a/src/api/restful/buy/marketing/index.ts b/src/api/restful/buy/marketing/index.ts
index dbe46703..5858202c 100644
--- a/src/api/restful/buy/marketing/index.ts
+++ b/src/api/restful/buy/marketing/index.ts
@@ -1,6 +1,4 @@
import {
- BuyMarketingGetAlsoBoughtByProductParams,
- BuyMarketingGetAlsoViewedByProductParams,
BuyMarketingGetMerchandisedProductsParams
} from '../../../../types/index.js';
import {operations} from '../../../../types/restful/specs/buy_marketing_v1_beta_oas3.js';
@@ -23,27 +21,6 @@ export default class Marketing extends Restful implements OpenApi {
// Client Credentials: https://api.ebay.com/oauth/api_scope/buy.marketing
//
- /**
- * This call returns products that were also bought when shoppers bought the product specified in the request.
- * @param params
- */
- public getAlsoBoughtByProduct(params: BuyMarketingGetAlsoBoughtByProductParams) {
- return this.get('/merchandised_product/get_also_bought_products', {
- params
- });
- }
-
- /**
- * This call returns products that were also viewed when shoppers viewed the product specified in the request.
- *
- * @param params
- */
- public getAlsoViewedByProduct(params: BuyMarketingGetAlsoViewedByProductParams) {
- return this.get('/merchandised_product/get_also_viewed_products', {
- params
- });
- }
-
/**
* This call returns an array of products based on the category and metric specified.
*
diff --git a/src/api/restful/buy/order/index.ts b/src/api/restful/buy/order/index.ts
index 4e0e56c1..ce17eb50 100644
--- a/src/api/restful/buy/order/index.ts
+++ b/src/api/restful/buy/order/index.ts
@@ -1,20 +1,20 @@
import {
- CheckoutSessionRequestWithoutPayment,
CouponRequest,
CreateGuestCheckoutSessionRequest,
- CreateSignInCheckoutSessionRequest,
- GuestPlaceOrderRequest,
- InitiatePaymentRequest,
ShippingAddressImpl,
- UpdatePaymentInformation,
UpdateQuantity,
UpdateShippingOption
} from '../../../../types/index.js';
-import {operations} from '../../../../types/restful/specs/buy_order_v1_beta_oas3.js';
+import {operations} from '../../../../types/restful/specs/buy_order_v2_oas3.js';
import Api, {OpenApi} from '../../index.js';
/**
- * The Order API provides interfaces that lets shoppers pay for items (for both eBay guest and eBay member buyers).
+ * The Order API provides interfaces that let eBay guest buyers pay for items.
+ *
+ * As of Order API v2, only the guest checkout flow is available. The member checkout session,
+ * proxy-guest checkout session, payment-info, initiate-payment and place-order operations from
+ * v1 were removed by eBay and are no longer part of the API.
+ *
* Client Credentials: https://api.ebay.com/oauth/api_scope/buy.order
*/
export default class Order extends Api implements OpenApi {
@@ -22,140 +22,16 @@ export default class Order extends Api implements OpenApi {
static id = 'Order';
get basePath(): string {
- return '/buy/order/v1';
+ return '/buy/order/v2';
}
/**
- * (Limited Release) You must be whitelisted to use this method.
- * This method adds a coupon to an eBay proxy guest checkout session and applies it to all the eligible items in
- * the order.
- *
- * @param {String} checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is
- * returned by the initiateCheckoutSession method.
- * @param body The container for the fields used to apply a coupon to a checkout session.
- */
- public applyCoupon(checkoutSessionId: string, body: CouponRequest) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/checkout_session/${checkoutSessionId}/apply_coupon`, body);
- }
-
- /**
- * This method returns the details of the specified eBay member checkout session.
- *
- * @param {String} checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is
- * returned by the initiateCheckoutSession method.
- */
- public getCheckoutSession(checkoutSessionId: string) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.get(`/checkout_session/${checkoutSessionId}`);
- }
-
- /**
- * This method creates a eBay member checkout session, which is the first step in performing a checkout.
- *
- * @param body The container for the fields used by the initiateCheckoutSession method.
- */
- public initiateCheckoutSession(body?: CreateSignInCheckoutSessionRequest) {
- return this.post('/checkout_session/initiate', body);
- }
-
- /**
- * This method creates the purchase order, pays for the items, and terminates the specified eBay member checkout
- * session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- */
- public placeOrder(checkoutSessionId: string) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/checkout_session/${checkoutSessionId}/place_order`);
- }
-
- /**
- * (Limited Release) You must be whitelisted to use this method. This method removes a coupon from an eBay member
- * checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body CouponRequest
- */
- public removeCoupon(checkoutSessionId: string, body?: CouponRequest) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/checkout_session/${checkoutSessionId}/remove_coupon`, body);
- }
-
- /**
- * This method changes the payment method information of the specified eBay member checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body UpdatePaymentInformation
- */
- public updatePaymentInfo(checkoutSessionId: string, body?: UpdatePaymentInformation) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/checkout_session/${checkoutSessionId}/update_payment_info`, body);
- }
-
- /**
- * This method changes the quantity of the specified line item in an eBay member checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body UpdateQuantity
- */
- public updateQuantity(checkoutSessionId: string, body?: UpdateQuantity) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/checkout_session/${checkoutSessionId}/update_quantity`, body);
- }
-
- /**
- * This method changes the quantity of the specified line item in an eBay member checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body UpdateQuantity
- */
- public checkoutSessionId(checkoutSessionId: string, body?: UpdateQuantity) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/checkout_session/${checkoutSessionId}/update_quantity`, body);
- }
-
- /**
- * This method changes the shipping address for in an eBay member checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body ShippingAddressImpl
- */
- public updateShippingAddress(checkoutSessionId: string, body?: ShippingAddressImpl) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/checkout_session/${checkoutSessionId}/update_shipping_address`, body);
- }
-
- /**
- * This method changes the shipping method for the specified line item in an eBay member checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body UpdateShippingOption
- */
- public updateShippingOption(checkoutSessionId: string, body?: UpdateShippingOption) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/checkout_session/${checkoutSessionId}/update_shipping_option`, body);
- }
-
- /**
- * (Limited Release) You must be whitelisted to use this method. This method adds a coupon to an eBay guest
- * checkout
- * session and applies it to all the eligible items in the order.
+ * This method creates an eBay guest checkout session, which is the first step in performing a checkout.
*
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body CouponRequest
+ * @param body CreateGuestCheckoutSessionRequest
*/
- public applyGuestCoupon(checkoutSessionId: string, body?: CouponRequest) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/guest_checkout_session/${checkoutSessionId}/apply_coupon`, body);
+ public initiateGuestCheckoutSession(body?: CreateGuestCheckoutSessionRequest) {
+ return this.post('/guest_checkout_session/initiate', body);
}
/**
@@ -163,7 +39,7 @@ export default class Order extends Api implements OpenApi {
* URI parameter and is required.
*
* @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
+ * initiateGuestCheckoutSession method.
*/
public getGuestCheckoutSession(checkoutSessionId: string) {
checkoutSessionId = encodeURIComponent(checkoutSessionId);
@@ -171,36 +47,16 @@ export default class Order extends Api implements OpenApi {
}
/**
- * This method creates an eBay guest checkout session, which is the first step in performing a checkout.
- *
- * @param body CheckoutSessionRequest
- */
- public initiateGuestCheckoutSession(body?: CreateGuestCheckoutSessionRequest) {
- return this.post('/guest_checkout_session/initiate', body);
- }
-
- /**
- * This method is used only in the PayPal Smart Button eBay guest payment flow.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body InitiatePaymentRequest
- */
- public initiateGuestPayment(checkoutSessionId: string, body?: InitiatePaymentRequest) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/guest_checkout_session/${checkoutSessionId}/initiate_payment`, body);
- }
-
- /**
- * This method creates the purchase order, pays for the items, and terminates the specified guest checkout session.
+ * (Limited Release) You must be whitelisted to use this method. This method adds a coupon to an eBay guest
+ * checkout session and applies it to all the eligible items in the order.
*
* @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body GuestPlaceOrderRequest
+ * initiateGuestCheckoutSession method.
+ * @param body CouponRequest
*/
- public placeGuestOrder(checkoutSessionId: string, body?: GuestPlaceOrderRequest) {
+ public applyGuestCoupon(checkoutSessionId: string, body?: CouponRequest) {
checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/guest_checkout_session/${checkoutSessionId}/place_order`, body);
+ return this.post(`/guest_checkout_session/${checkoutSessionId}/apply_coupon`, body);
}
/**
@@ -208,7 +64,7 @@ export default class Order extends Api implements OpenApi {
* checkout session.
*
* @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
+ * initiateGuestCheckoutSession method.
* @param body CouponRequest
*/
public removeGuestCoupon(checkoutSessionId: string, body?: CouponRequest) {
@@ -216,23 +72,11 @@ export default class Order extends Api implements OpenApi {
return this.post(`/guest_checkout_session/${checkoutSessionId}/remove_coupon`, body);
}
- /**
- * This method changes the payment method information of the specified guest checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body UpdatePaymentInformation
- */
- public updateGuestPaymentInfo(checkoutSessionId: string, body?: UpdatePaymentInformation) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/guest_checkout_session/${checkoutSessionId}/update_payment_info`, body);
- }
-
/**
* This method changes the quantity of the specified line item in an eBay guest checkout session.
*
* @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
+ * initiateGuestCheckoutSession method.
* @param body UpdateQuantity
*/
public updateGuestQuantity(checkoutSessionId: string, body?: UpdateQuantity) {
@@ -244,7 +88,7 @@ export default class Order extends Api implements OpenApi {
* This method changes the shipping address for the order in an eBay guest checkout session.
*
* @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
+ * initiateGuestCheckoutSession method.
* @param body ShippingAddressImpl
*/
public updateGuestShippingAddress(checkoutSessionId: string, body?: ShippingAddressImpl) {
@@ -256,7 +100,7 @@ export default class Order extends Api implements OpenApi {
* This method changes the shipping method for the specified line item in an eBay guest checkout session.
*
* @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
+ * initiateGuestCheckoutSession method.
* @param body UpdateShippingOption
*/
public updateGuestShippingOption(checkoutSessionId: string, body?: UpdateShippingOption) {
@@ -264,134 +108,6 @@ export default class Order extends Api implements OpenApi {
return this.post(`/guest_checkout_session/${checkoutSessionId}/update_shipping_option`, body);
}
- /**
- * (Limited Release) You must be whitelisted to use this method. This method adds a coupon to an eBay proxy guest
- * checkout session and applies it to all the eligible items in the order.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body CouponRequest
- */
- public applyProxyGuestCoupon(checkoutSessionId: string, body?: CouponRequest) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/proxy_guest_checkout_session/${checkoutSessionId}/apply_coupon`, body);
- }
-
- /**
- * This method returns the details of the specified eBay proxy guest checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- */
- public getProxyGuestCheckoutSession(checkoutSessionId: string) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.get(`/proxy_guest_checkout_session/${checkoutSessionId}`);
- }
-
- /**
- * This method creates an eBay proxy guest checkout session, which is a payment flow that requires apps
- * with a VSP (vault service provider), such as Braintree. The VSP handles only the methods within this flow that
- * contain payment information.
- *
- * @param body CheckoutSessionRequest
- */
- public initiateProxyGuestCheckoutSession(body?: CheckoutSessionRequestWithoutPayment) {
- return this.post('/proxy_guest_checkout_session/initiate', body);
- }
-
- /**
- * This method creates the proxy guest purchase order, pays for the items, and terminates the specified guest
- * checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body GuestPlaceOrderRequest
- */
- public placeProxyGuestOrder(checkoutSessionId: string, body?: GuestPlaceOrderRequest) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/proxy_guest_checkout_session/${checkoutSessionId}/place_order`, body);
- }
-
- /**
- * (Limited Release) You must be whitelisted to use this method. This method removes a coupon from an eBay proxy
- * guest checkout session. The checkoutSessionId is passed in as a URI parameter and is required.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body CouponRequest
- */
- public removeProxyGuestCoupon(checkoutSessionId: string, body?: CouponRequest) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/proxy_guest_checkout_session/${checkoutSessionId}/remove_coupon`, body);
- }
-
- /**
- * This method adds or changes the payment information of the specified proxy guest checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param authorization The oAuth2 token. Note: The eBay partner must include this header in the request.
- * @param date The UTC timestamp of the request, which is generated and added to the request by the VSP.
- * @param requestNonce A UUID (a 128-bit universal unique ID), which is generated and added to the request by the
- * VSP.
- * @param signature The HMAC signature, which is generated and added to the request by the VSP.
- * @param body UpdatePaymentInformation
- */
- public updateProxyGuestPaymentInfo(
- checkoutSessionId: string,
- authorization: string,
- date: string,
- requestNonce: string,
- signature: string,
- body?: UpdatePaymentInformation
- ) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/proxy_guest_checkout_session/${checkoutSessionId}/update_payment_info`, body, {
- headers: {
- 'Authorization': authorization,
- 'X-EBAY-C-DATE': date,
- 'X-EBAY-C-REQUEST-NONCE': requestNonce,
- 'X-EBAY-C-SIGNATURE': signature
- }
- });
- }
-
- /**
- * This method changes the quantity of the specified line item in an eBay proxy guest checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body UpdateQuantity
- */
- public updateProxyGuestQuantity(checkoutSessionId: string, body?: UpdateQuantity) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/proxy_guest_checkout_session/${checkoutSessionId}/update_quantity`, body);
- }
-
- /**
- * This method changes the shipping address for the order in an eBay proxy guest checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body ShippingAddressImpl
- */
- public updateProxyGuestShippingAddress(checkoutSessionId: string, body?: ShippingAddressImpl) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/proxy_guest_checkout_session/${checkoutSessionId}/update_shipping_address`, body);
- }
-
- /**
- * This method changes the shipping method for the specified line item in an eBay proxy guest checkout session.
- *
- * @param checkoutSessionId The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the
- * initiateCheckoutSession method.
- * @param body UpdateShippingOption
- */
- public updateProxyGuestShippingOption(checkoutSessionId: string, body?: UpdateShippingOption) {
- checkoutSessionId = encodeURIComponent(checkoutSessionId);
- return this.post(`/proxy_guest_checkout_session/${checkoutSessionId}/update_shipping_option`, body);
- }
-
/**
* This method retrieves the details about a specific guest purchase order.
*
@@ -402,15 +118,4 @@ export default class Order extends Api implements OpenApi {
purchaseOrderId = encodeURIComponent(purchaseOrderId);
return this.get(`/guest_purchase_order/${purchaseOrderId}`);
}
-
- /**
- * This method retrieves the details about a specific eBay member purchase order.
- *
- * @param purchaseOrderId The unique identifier of a purchase order made by an eBay member, for which details are
- * to be retrieved.
- */
- public getPurchaseOrder(purchaseOrderId: string) {
- purchaseOrderId = encodeURIComponent(purchaseOrderId);
- return this.get(`/purchase_order/${purchaseOrderId}`);
- }
}
diff --git a/src/api/restful/commerce/catalog/index.ts b/src/api/restful/commerce/catalog/index.ts
index 310cd1d2..6d661b6d 100644
--- a/src/api/restful/commerce/catalog/index.ts
+++ b/src/api/restful/commerce/catalog/index.ts
@@ -5,7 +5,7 @@ import Restful, {OpenApi} from '../../index.js';
/**
* Use the Catalog API to search the eBay catalog for products on which to base a seller's item listing;
*/
-export default class Catalog extends Restful implements OpenApi> {
+export default class Catalog extends Restful implements OpenApi {
static id = 'Catalog';
@@ -13,37 +13,6 @@ export default class Catalog extends Restful implements OpenApi {
}
});
}
-
- /**
- * This call allows users to retrieve the details for a specific charitable organization using its legacy charity ID, which has also been referred to as the charity number, external ID, and PayPal Giving Fund ID.
- *
- * @param legacyCharityOrgId The legacy ID of the charitable organization.
- */
- public getCharityOrgByLegacyId(legacyCharityOrgId: string) {
- return this.get('/charity_org/get_charity_org_by_legacy_id', {
- params: {
- legacy_charity_org_id: legacyCharityOrgId
- }
- });
- }
}
diff --git a/src/api/restful/commerce/media/index.ts b/src/api/restful/commerce/media/index.ts
index 0bbec921..99c50133 100644
--- a/src/api/restful/commerce/media/index.ts
+++ b/src/api/restful/commerce/media/index.ts
@@ -1,5 +1,11 @@
-import {CreateVideoRequest, InputStream} from '../../../../types/index.js';
+import {
+ CreateVideoRequest,
+ CreateImageFromUrlRequest,
+ CreateDocumentRequest,
+ CreateDocumentFromUrlRequest
+} from '../../../../types/index.js';
import {operations} from '../../../../types/restful/specs/commerce_media_v1_beta_oas3.js';
+import {multipartHeader, octetStreamHeader} from '../../../../request.js';
import Restful, {OpenApi} from '../../index.js';
/**
@@ -18,6 +24,35 @@ export default class Media extends Restful implements OpenApi {
return 'apim';
}
+ /**
+ * This method creates an image from a file upload.
+ * @param body The image file to upload
+ */
+ async createImageFromFile(body?: any) {
+ return this.post('/image/create_image_from_file', body, {
+ headers: {
+ ...multipartHeader
+ }
+ });
+ }
+
+ /**
+ * This method creates an image from a URL.
+ * @param body The image URL request
+ */
+ async createImageFromUrl(body?: CreateImageFromUrlRequest) {
+ return this.post('/image/create_image_from_url', body);
+ }
+
+ /**
+ * This method retrieves an image's metadata and content given a specified image ID.
+ * @param imageId The unique identifier of the image to be retrieved.
+ */
+ async getImage(imageId: string) {
+ imageId = encodeURIComponent(imageId);
+ return this.get(`/image/${imageId}`);
+ }
+
/**
* This method creates a video. When using this method, specify the title, size, and classification of the video to be created.
* @param body the CreateVideoRequest
@@ -40,9 +75,86 @@ export default class Media extends Restful implements OpenApi {
*
* @param videoId The unique identifier of the video to be uploaded.
* @param body The request payload for this method is the input stream for the video source. The input source must be an .mp4 file of the type MPEG-4 Part 10 or Advanced Video Coding (MPEG-4 AVC).
+ * @param headers Optional additional headers. Pass Content-Length and Content-Range here to resume an interrupted upload.
*/
- async uploadVideo(videoId: string, body?: InputStream) {
+ async uploadVideo(videoId: string, body?: any, headers: Record = {}) {
videoId = encodeURIComponent(videoId);
- return this.post(`/video/${videoId}/upload`, body);
+ return this.post(`/video/${videoId}/upload`, body, {
+ headers: {
+ ...octetStreamHeader,
+ ...headers
+ }
+ });
+ }
+
+ /**
+ * This method creates a document.
+ * @param body The document creation request
+ */
+ async createDocument(body?: CreateDocumentRequest) {
+ return this.post('/document', body);
+ }
+
+ /**
+ * This method creates a document from a URL.
+ * @param body The document URL request
+ */
+ async createDocumentFromUrl(body?: CreateDocumentFromUrlRequest) {
+ return this.post('/document/create_document_from_url', body);
+ }
+
+ /**
+ * This method retrieves a document's metadata and content given a specified document ID.
+ * @param documentId The unique identifier of the document to be retrieved.
+ */
+ async getDocument(documentId: string) {
+ documentId = encodeURIComponent(documentId);
+ return this.get(`/document/${documentId}`);
+ }
+
+ /**
+ * This method associates the specified file with the specified document ID and uploads the input file.
+ * @param documentId The unique identifier of the document to be uploaded.
+ * @param body The document file to upload
+ */
+ async uploadDocument(documentId: string, body?: any) {
+ documentId = encodeURIComponent(documentId);
+ return this.post(`/document/${documentId}/upload`, body, {
+ headers: {
+ ...multipartHeader
+ }
+ });
+ }
+
+ /**
+ * This method uploads a post-order document.
+ * @param body The post-order document file to upload.
+ */
+ async uploadPostOrderDocument(body?: any) {
+ return this.post('/post_order/document', body, {
+ headers: {
+ ...multipartHeader
+ }
+ });
+ }
+
+ /**
+ * This method downloads a post-order document's content given a specified document ID.
+ * @param documentId The unique identifier of the post-order document to be downloaded.
+ */
+ async downloadPostOrderDocument(documentId: string) {
+ documentId = encodeURIComponent(documentId);
+ return this.get(`/post_order/document/${documentId}`, {
+ responseType: 'arraybuffer'
+ });
+ }
+
+ /**
+ * This method removes a post-order document given a specified document ID.
+ * @param documentId The unique identifier of the post-order document to be removed.
+ */
+ async removePostOrderDocument(documentId: string) {
+ documentId = encodeURIComponent(documentId);
+ return this.delete(`/post_order/document/${documentId}`);
}
}
diff --git a/src/api/restful/commerce/notification/index.ts b/src/api/restful/commerce/notification/index.ts
index 90c75b12..7640576e 100644
--- a/src/api/restful/commerce/notification/index.ts
+++ b/src/api/restful/commerce/notification/index.ts
@@ -3,7 +3,8 @@ import {
CreateSubscriptionRequest,
DestinationRequest,
NotificationParams,
- UpdateSubscriptionRequest
+ UpdateSubscriptionRequest,
+ CreateSubscriptionFilterRequest
} from '../../../../types/index.js';
import {operations} from '../../../../types/restful/specs/commerce_notification_v1_oas3.js';
import Restful, {OpenApi} from '../../index.js';
@@ -128,12 +129,47 @@ export default class Notification extends Restful implements OpenApi
return this.post(`/subscription/${subscriptionId}/disable`);
}
+ /**
+ * This method creates a subscription filter for the specified subscription.
+ *
+ * @param subscriptionId The unique identifier for the subscription.
+ * @param body The subscription filter request.
+ */
+ public createSubscriptionFilter(subscriptionId: string, body?: CreateSubscriptionFilterRequest) {
+ subscriptionId = encodeURIComponent(subscriptionId);
+ return this.post(`/subscription/${subscriptionId}/filter`, body);
+ }
+
+ /**
+ * This method retrieves the subscription filter for the specified subscription.
+ *
+ * @param subscriptionId The unique identifier for the subscription.
+ * @param filterId The unique identifier for the filter.
+ */
+ public getSubscriptionFilter(subscriptionId: string, filterId: string) {
+ subscriptionId = encodeURIComponent(subscriptionId);
+ filterId = encodeURIComponent(filterId);
+ return this.get(`/subscription/${subscriptionId}/filter/${filterId}`);
+ }
+
+ /**
+ * This method deletes the subscription filter for the specified subscription.
+ *
+ * @param subscriptionId The unique identifier for the subscription.
+ * @param filterId The unique identifier for the filter.
+ */
+ public deleteSubscriptionFilter(subscriptionId: string, filterId: string) {
+ subscriptionId = encodeURIComponent(subscriptionId);
+ filterId = encodeURIComponent(filterId);
+ return this.delete(`/subscription/${subscriptionId}/filter/${filterId}`);
+ }
+
/**
* This method triggers a mocked test payload that includes a notification ID, publish date, and so on.
*
* @param subscriptionId The unique identifier for the subscription.
*/
- public test(subscriptionId: string) {
+ public testSubscription(subscriptionId: string) {
subscriptionId = encodeURIComponent(subscriptionId);
return this.post(`/subscription/${subscriptionId}/test`);
}
diff --git a/src/api/restful/commerce/taxonomy/index.ts b/src/api/restful/commerce/taxonomy/index.ts
index a05b8e8e..997aba44 100644
--- a/src/api/restful/commerce/taxonomy/index.ts
+++ b/src/api/restful/commerce/taxonomy/index.ts
@@ -146,4 +146,14 @@ export default class Taxonomy extends Restful implements OpenApi {
responseType: 'arraybuffer'
});
}
+
+ /**
+ * This call returns any eBay leaf categories in the specified category tree that have expired and the currently active leaf categories that have replaced them.
+ *
+ * @param categoryTreeId The unique identifier of the eBay category tree for which expired categories are being requested.
+ */
+ public getExpiredCategories(categoryTreeId: string) {
+ categoryTreeId = encodeURIComponent(categoryTreeId);
+ return this.get(`/category_tree/${categoryTreeId}/get_expired_categories`);
+ }
}
diff --git a/src/api/restful/index.ts b/src/api/restful/index.ts
index 83c20d9d..b85d74b9 100644
--- a/src/api/restful/index.ts
+++ b/src/api/restful/index.ts
@@ -148,8 +148,12 @@ export default abstract class Restful extends Api {
return this.doRequest({method: 'get', path, config}, apiConfig);
}
+ /**
+ * A DELETE body travels in `config.data`, the way Axios expects it. Mirror it onto the request so
+ * that digital signing sees the payload and emits a "content-digest" header for it.
+ */
public async delete(path: string, config: any = {}, apiConfig?: RestfulApiConfig) {
- return this.doRequest({method: 'delete', path, config}, apiConfig);
+ return this.doRequest({method: 'delete', path, data: config.data, config}, apiConfig);
}
public async post(path: string, data?: any, config: any = {}, apiConfig?: RestfulApiConfig) {
@@ -160,6 +164,10 @@ export default abstract class Restful extends Api {
return this.doRequest({method: 'put', path, data, config}, apiConfig);
}
+ public async patch(path: string, data?: any, config: any = {}, apiConfig?: RestfulApiConfig) {
+ return this.doRequest({method: 'patch', path, data, config}, apiConfig);
+ }
+
get additionalHeaders() {
return Object.keys(additionalHeaders)
// @ts-ignore
@@ -183,20 +191,21 @@ export default abstract class Restful extends Api {
path: apiConfig.apiVersion + apiConfig.basePath + apiRequest.path
}, payload) : {};
+ // Least to most specific: library defaults are overridable by the app config, which in turn is
+ // overridable by per-request headers (e.g. the multipart/octet-stream Content-Type that upload
+ // endpoints require). Signature headers are derived from the final request and always win.
const headers = {
...defaultApiHeaders,
...this.additionalHeaders,
...authHeader,
...apiConfig.headers,
+ ...(apiRequest.config.headers || {}),
...signatureHeaders
};
return {
...apiRequest.config,
- headers: {
- ...(apiRequest.config.headers || {}),
- ...headers
- }
+ headers
};
}
diff --git a/src/api/restful/postOrder/cancellation/index.ts b/src/api/restful/postOrder/cancellation/index.ts
index a9318163..012d188a 100644
--- a/src/api/restful/postOrder/cancellation/index.ts
+++ b/src/api/restful/postOrder/cancellation/index.ts
@@ -1,7 +1,6 @@
import Restful from '../../index.js';
import {
CancellationSearchParams,
- ConfirmRefundRequest,
CreateCancelRequest,
RejectCancelRequest
} from '../../../../types/index.js';
@@ -42,17 +41,6 @@ export default class Cancellation extends Restful {
});
}
- /**
- * Buyer confirms the refund from a cancellation was received
- *
- * @param cancelId The unique eBay-assigned identifier of the cancellation/refund being confirmed.
- * @param payload the ConfirmRefundReceivedPayload
- */
- public confirmRefundReceived(cancelId: string, payload?: ConfirmRefundRequest) {
- cancelId = encodeURIComponent(cancelId);
- return this.post(`/cancellation/${cancelId}/confirm`, payload);
- }
-
/**
* Request or perform an order cancellation.
*
diff --git a/src/api/restful/postOrder/case/index.ts b/src/api/restful/postOrder/case/index.ts
index 2e0c816b..887734fc 100644
--- a/src/api/restful/postOrder/case/index.ts
+++ b/src/api/restful/postOrder/case/index.ts
@@ -1,9 +1,6 @@
import {
AppealRequest,
- BuyerCloseCaseRequest,
- CaseSearchParams,
- ReturnAddressRequest,
- Text
+ CaseSearchParams
} from '../../../../types/index.js';
import Restful from '../../index.js';
@@ -33,17 +30,6 @@ export default class Case extends Restful {
return this.post(`/casemanagement/${id}/appeal`, payload);
}
- /**
- * Check the eligibility of an order cancellation.
- *
- * @param caseId The unique identifier of a case.
- * @param payload the BuyerCloseCaseRequest
- */
- public closeCase(caseId: string, payload: BuyerCloseCaseRequest) {
- const id = encodeURIComponent(caseId);
- return this.post(`/casemanagement/${id}/close`, payload);
- }
-
/**
* Retrieve the details related to a specific case.
*
@@ -54,46 +40,6 @@ export default class Case extends Restful {
return this.get(`/casemanagement/${id}`);
}
- /**
- * Seller issues a refund for a case.
- *
- * @param caseId The unique identifier of a case.
- * @param payload the CaseVoluntaryRefundRequest (Text)
- */
- public issueCaseRefund(caseId: string, payload?: Text) {
- const id = encodeURIComponent(caseId);
- return this.post(`/casemanagement/${id}/issue_refund`, payload);
- }
-
- /**
- * This call allows the buyer to provide shipment tracking information for the item that is being returned to the
- * seller.
- *
- * @param caseId The unique identifier of a case.
- * @param shippingCarrierName The shipping carrier that is used to ship the item, such as 'FedEx', 'UPS', or
- * 'USPS'.
- * @param trackingNumber The tracking number assigned by the shipping carrier to the item shipment.
- */
- public provideReturnShipmentInfo(caseId: string, {shippingCarrierName, trackingNumber}:
- { shippingCarrierName: string, trackingNumber: string }) {
- const id = encodeURIComponent(caseId);
- return this.post(`/casemanagement/${id}/provide_shipment_info`, {
- shippingCarrierName,
- trackingNumber
- });
- }
-
- /**
- * Seller provides a return address to the buyer.
- *
- * @param cancelId The unique eBay-assigned identifier of the cancellation request to be rejected.
- * @param payload the ReturnAddressRequest
- */
- public providesReturnAddress(cancelId: string, payload?: ReturnAddressRequest) {
- const id = encodeURIComponent(cancelId);
- return this.post(`/casemanagement/${id}/provide_return_address`, payload);
- }
-
/**
* This call is used to search for cases using multiple filter types.
*
diff --git a/src/api/restful/postOrder/inquiry/index.ts b/src/api/restful/postOrder/inquiry/index.ts
index f4c352cd..30e5c3ed 100644
--- a/src/api/restful/postOrder/inquiry/index.ts
+++ b/src/api/restful/postOrder/inquiry/index.ts
@@ -1,12 +1,8 @@
import Restful from '../../index.js';
import {
- BuyerCloseInquiryRequest,
- CheckInquiryEligibilityRequest,
- CreateInquiryRequest,
EscalateInquiryRequest,
InquirySearchParams,
InquiryVoluntaryRefundRequest,
- SellerProvideRefundInfoRequest,
SendMessageRequest,
ShipmentInfoRequest
} from '../../../../types/index.js';
@@ -26,51 +22,6 @@ export default class Inquiry extends Restful {
return true;
}
- /**
- * Check if a buyer is eligible to open an inquiry on an order.
- *
- * @param payload the CheckInquiryEligibilityRequest
- */
- public checkInquiryEligibility(payload: CheckInquiryEligibilityRequest) {
- return this.post('/inquiry/check_eligibility', payload);
- }
-
- /**
- * Close an inquiry for the buyer
- *
- * @param inquiryId The unique ID of the inquiry to be closed.
- * @param payload the BuyerCloseInquiryRequest
- */
- public closeInquiry(inquiryId: string, payload?: BuyerCloseInquiryRequest) {
- inquiryId = encodeURIComponent(inquiryId);
- if (typeof payload?.closeReason === 'string') {
- payload.closeReason = payload.closeReason.trim();
- }
- return this.post(`/inquiry/${inquiryId}/close`, payload);
- }
-
- /**
- * Buyer confirms the refund from an inquiry was received
- *
- * @param inquiryId The unique identifier of a case.
- */
- public confirmInquiryRefund(inquiryId: string) {
- inquiryId = encodeURIComponent(inquiryId);
- return this.post(`/inquiry/${inquiryId}/confirm_refund`);
- }
-
- /**
- * Create an inquiry for the buyer.
- *
- * @param payload the CreateInquiryRequest
- */
- public createInquiry(payload: CreateInquiryRequest) {
- if (typeof payload.desiredOutcome === 'string') {
- payload.desiredOutcome = payload.desiredOutcome.trim();
- }
- return this.post('/inquiry', payload);
- }
-
/**
* Escalate an inquiry to an INR case.
*
@@ -104,17 +55,6 @@ export default class Inquiry extends Restful {
return this.post(`/inquiry/${inquiryId}/issue_refund`, payload);
}
- /**
- * Provide refund information about an inquiry to the buyer.
- *
- * @param inquiryId The unique ID of the inquiry for which to provide refund information.
- * @param payload the InquiryVoluntaryRefundRequest
- */
- public provideInquiryRefundInfo(inquiryId: string, payload: SellerProvideRefundInfoRequest) {
- inquiryId = encodeURIComponent(inquiryId);
- return this.post(`/inquiry/${inquiryId}/provide_refund_info`, payload);
- }
-
/**
* Provide shipment information for an inquiry.
*
diff --git a/src/api/restful/postOrder/return/index.ts b/src/api/restful/postOrder/return/index.ts
index 2d7957e9..0d742705 100644
--- a/src/api/restful/postOrder/return/index.ts
+++ b/src/api/restful/postOrder/return/index.ts
@@ -1,23 +1,14 @@
-import {FilePurpose, GetReturnFieldGroupEnum} from '../../../../enums/index.js';
+import {GetReturnFieldGroupEnum} from '../../../../enums/index.js';
import {
- CheckEligibilityRequest,
- CloseReturnRequest,
CreateReturnRequest,
DecideReturnRequest,
EscalateRequest,
- GetEstimateRequest,
MarkAsReceivedRequest,
- MarkAsShippedRequest,
- MarkRefundSentRequest,
PostOrderIssueRefundRequest,
ProvideLabelRequest,
- ReturnRequestType,
SearchReturnParams,
SendMessageRequest,
- SetReturnCreationSessionRequest,
- UpdateTrackingRequest,
- UploadFileRequest,
- VoidLabelRequest
+ UploadFileRequest
} from '../../../../types/index.js';
import Restful from '../../index.js';
@@ -47,48 +38,6 @@ export default class Return extends Restful {
return this.post(`/return/${id}/add_shipping_label`, payload);
}
- /**
- * Cancel a return request.
- *
- * @param returnId The unique eBay-assigned ID of the return request.
- * @param payload The CloseReturnRequest.
- */
- public cancelReturnRequest(returnId: string, payload?: CloseReturnRequest) {
- const id = encodeURIComponent(returnId);
- if (payload && payload.buyerCloseReason) {
- payload.buyerCloseReason = payload.buyerCloseReason.trim();
- }
- return this.post(`/return/${id}/cancel`, payload);
- }
-
- /**
- * Check to see if an item is eligible for a return.
- *
- * @param payload the CheckEligibilityRequest
- */
- public checkReturnEligibility(payload: CheckEligibilityRequest) {
- return this.post('/return/check_eligibility', payload);
- }
-
- /**
- * Validate the eligibility of an existing shipping label.
- *
- * @param returnId The unique eBay-assigned ID of the return.
- */
- public checkShippingLabelEligibility(returnId: string) {
- const id = encodeURIComponent(returnId);
- return this.get(`/return/${id}/check_label_print_eligibility`);
- }
-
- /**
- * Create a return draft.
- *
- * @param payload the SetReturnCreationSessionRequest
- */
- public createReturnDraft(payload: SetReturnCreationSessionRequest) {
- return this.post('/return/draft', payload);
- }
-
/**
* Request a return for an item.
*
@@ -103,29 +52,6 @@ export default class Return extends Restful {
});
}
- /**
- * Create an eBay shipping label for the buyer.
- *
- * @param returnId The unique eBay-assigned ID of the return.
- */
- public createReturnShippingLabel(returnId: string) {
- const id = encodeURIComponent(returnId);
- return this.post(`/return/${id}/initiate_shipping_label`);
- }
-
- /**
- * Delete a file associated with a return draft.
- *
- * @param draftId The unique eBay-assigned ID of the return draft.
- * @param fileId The unique eBay-assigned ID of the draft file.
- */
- public deleteReturnDraftFile(draftId: string, fileId: string) {
- draftId = encodeURIComponent(draftId);
- fileId = encodeURIComponent(fileId);
-
- return this.delete(`/return/draft/${draftId}/file/${fileId}`);
- }
-
/**
* Escalate an existing return to eBay customer support.
*
@@ -153,36 +79,7 @@ export default class Return extends Restful {
}
/**
- * Retrieve a return draft.
- *
- * @param returnId The unique eBay-assigned ID of the return request.
- */
- public getReturnDraft(returnId: string) {
- const id = encodeURIComponent(returnId);
- return this.get(`/return/draft/${id}`);
- }
-
- /**
- * Retrieve the files associated with a return draft.
- *
- * @param returnId The unique eBay-assigned ID of the return draft.
- */
- public getReturnDraftFiles(returnId: string) {
- const id = encodeURIComponent(returnId);
- return this.get(`/return/draft/${id}/files`);
- }
-
- /**
- * Retrieve the cost estimate of a refund with its shipping cost.
- *
- * @param payload the GetEstimateRequest
- */
- public getReturnEstimate(payload: GetEstimateRequest) {
- return this.post('/return/estimate', payload);
- }
-
- /**
- * Retrieve the cost estimate of a refund with its shipping cost.
+ * Retrieve the files associated with a return.
*
* @param returnId The unique eBay-assigned ID of the return.
*/
@@ -198,16 +95,6 @@ export default class Return extends Restful {
return this.get('/return/preference');
}
- /**
- * Retrieve the data for an existing shipping label.
- *
- * @param returnId The unique eBay-assigned ID of the return.
- */
- public getReturnShippingLabel(returnId: string) {
- returnId = encodeURIComponent(returnId);
- return this.get(`/return/${returnId}/get_shipping_label`);
- }
-
/**
* Retrieve shipment tracking activity for a return.
*
@@ -247,38 +134,6 @@ export default class Return extends Restful {
return this.post(`/return/${returnId}/mark_as_received`, payload);
}
- /**
- * Mark a refund as received.
- *
- * @param returnId The unique eBay-assigned ID of the return.
- */
- public markReturnRefundReceived(returnId: string) {
- returnId = encodeURIComponent(returnId);
- return this.post(`/return/${returnId}/mark_refund_received`);
- }
-
- /**
- * Notify the buyer that a refund has been issued.
- *
- * @param returnId The unique eBay-assigned ID of the return.
- * @param payload the MarkRefundSentRequest
- */
- public markReturnRefundSent(returnId: string, payload: MarkRefundSentRequest) {
- returnId = encodeURIComponent(returnId);
- return this.post(`/return/${returnId}/mark_refund_sent`, payload);
- }
-
- /**
- * Mark a return as shipped.
- *
- * @param returnId The unique eBay-assigned ID of the return.
- * @param payload the MarkAsShippedRequest
- */
- public markReturnShipped(returnId: string, payload?: MarkAsShippedRequest) {
- returnId = encodeURIComponent(returnId);
- return this.post(`/return/${returnId}/mark_as_shipped`, payload);
- }
-
/**
* Perform an action on a return, such as APPROVE.
*
@@ -313,22 +168,7 @@ export default class Return extends Restful {
}
/**
- * Send a shipping label to an email address.
- *
- * @param returnId The unique eBay-assigned ID of the return.
- * @param toEmailAddress The recipient's email address is specified in this field.
- */
- public sendReturnShippingLabel(returnId: string, toEmailAddress?: string) {
- returnId = encodeURIComponent(returnId);
- return this.post(`/return/${returnId}/send_shipping_label`, {}, {
- params: {
- to_email_address: toEmailAddress
- }
- });
- }
-
- /**
- * Send a shipping label to an email address.
+ * Set seller's return preferences.
*
* @param rmaRequired This field is included and set to true if the seller wishes to require that the buyer provide
* a Return Merchandise Authorization (RMA) when returning an item.
@@ -339,56 +179,6 @@ export default class Return extends Restful {
});
}
- /**
- * Activate the files associated with a return.
- *
- * @param returnId The unique eBay-assigned ID of the return.
- * @param filePurpose This value is used to indicate if the file(s) are being used to provide more information
- * about the condition of the item, or intended to provide more information about shipment tracking or about
- * the shipping label.
- */
- public submitReturnFile(returnId: string, filePurpose?: FilePurpose | keyof typeof FilePurpose) {
- returnId = encodeURIComponent(returnId);
- return this.post(`/return/${returnId}/file/submit`, {
- filePurpose
- });
- }
-
- /**
- * Update an existing return draft.
- *
- * @param draftId The unique eBay-assigned ID of the return draft.
- * @param returnRequest the ReturnRequestType
- */
- public updateReturnDraft(draftId: string, returnRequest: ReturnRequestType) {
- draftId = encodeURIComponent(draftId);
- return this.put(`/return/draft/${draftId}`, {
- returnRequest
- });
- }
-
- /**
- * Update shipment tracking information.
- *
- * @param returnId The unique eBay-assigned ID of the return request.
- * @param payload the UpdateTrackingRequest
- */
- public updateShipmentTrackingInfo(returnId: string, payload: UpdateTrackingRequest) {
- returnId = encodeURIComponent(returnId);
- return this.put(`/return/${returnId}/update_tracking`, payload);
- }
-
- /**
- * Upload the files relating to a return draft.
- *
- * @param draftId The unique eBay-assigned ID of the return draft.
- * @param payload the UploadFileRequest
- */
- public uploadReturnDraftFile(draftId: string, payload: UploadFileRequest) {
- draftId = encodeURIComponent(draftId);
- return this.post(`/return/draft/${draftId}/file/upload`, payload);
- }
-
/**
* Upload the files relating to a return.
*
@@ -399,15 +189,4 @@ export default class Return extends Restful {
returnId = encodeURIComponent(returnId);
return this.post(`/return/${returnId}/file/upload`, payload);
}
-
- /**
- * Void a shipping label.
- *
- * @param returnId The unique eBay-assigned ID of the return.
- * @param payload the VoidLabelRequest
- */
- public voidShippingLabel(returnId: string, payload: VoidLabelRequest) {
- returnId = encodeURIComponent(returnId);
- return this.post(`/return/${returnId}/void_shipping_label`, payload);
- }
}
diff --git a/src/api/restful/sell/account/v1.ts b/src/api/restful/sell/account/v1.ts
index 0e90b8f0..071f1053 100644
--- a/src/api/restful/sell/account/v1.ts
+++ b/src/api/restful/sell/account/v1.ts
@@ -1,11 +1,10 @@
import {PaymentsProgramType} from '../../../../enums/index.js';
import {
+ BulkSalesTaxInput,
CustomPolicyCreateRequest,
CustomPolicyRequest,
FulfillmentPolicyRequest,
FulfillmentSellAccountProgram,
- InventoryLocation,
- InventoryLocationFull,
PaymentPolicyRequest,
ReturnPolicyRequest,
SalesTaxBase
@@ -380,6 +379,15 @@ export default class AccountV1 extends Restful implements OpenApi {
return this.put(`/sales_tax/${countryCode}/${jurisdictionId}`, body);
}
+ /**
+ * This method creates or replaces multiple sales tax table entries in a single bulk request.
+ *
+ * @param body A container with the list of sales tax table entries to create or replace.
+ */
+ public bulkCreateOrReplaceSalesTax(body: BulkSalesTaxInput) {
+ return this.post('/bulk_create_or_replace_sales_tax', body);
+ }
+
/**
* This call deletes a tax table entry for a jurisdiction.
*
@@ -441,84 +449,4 @@ export default class AccountV1 extends Restful implements OpenApi {
});
}
- /**
- * This call retrieves all defined details of the inventory location that is specified by the merchantLocationKey path parameter.
- * @param merchantLocationKey A unique merchant-defined key (ID) for an inventory location.
- */
- public getInventoryLocation(merchantLocationKey: string) {
- merchantLocationKey = encodeURIComponent(merchantLocationKey);
- return this.get(`/location/${merchantLocationKey}`);
- }
-
-
- /**
- * Use this call to create a new inventory location.
- * @param merchantLocationKey A unique, merchant-defined key (ID) for an inventory location.
- * @param body Inventory Location details
- */
- public createInventoryLocation(merchantLocationKey: string, body: InventoryLocationFull) {
- merchantLocationKey = encodeURIComponent(merchantLocationKey);
- return this.post(`/location/${merchantLocationKey}`, body);
- }
-
- /**
- *
This call deletes the inventory location that is specified in the merchantLocationKey path parameter.
- * @param merchantLocationKey
- */
- public deleteInventoryLocation(merchantLocationKey: string) {
- merchantLocationKey = encodeURIComponent(merchantLocationKey);
- return this.delete(`/location/${merchantLocationKey}`);
- }
-
- /**
- *
This call disables the inventory location that is specified in the merchantLocationKey path parameter.
- * @param merchantLocationKey A unique merchant-defined key (ID) for an inventory location.
- */
- public disableInventoryLocation(merchantLocationKey: string) {
- merchantLocationKey = encodeURIComponent(merchantLocationKey);
- return this.post(`/location/${merchantLocationKey}/disable`);
- }
-
- /**
- *
This call enables a disabled inventory location that is specified in the merchantLocationKey path parameter.
- * @param merchantLocationKey A unique merchant-defined key (ID) for an inventory location.
- */
- public enableInventoryLocation(merchantLocationKey: string) {
- merchantLocationKey = encodeURIComponent(merchantLocationKey);
- return this.post(`/location/${merchantLocationKey}/enable`);
- }
-
- /**
- * This call retrieves all defined details for every inventory location associated with the seller's account.
- * @param limit The value passed in this query parameter sets the maximum number of records to return per page of data.
- * @param offset Specifies the number of locations to skip in the result set before returning the first location in the paginated response.
- */
- public getInventoryLocations({limit, offset}: { limit?: number, offset?: number } = {}) {
- return this.get('/location', {
- params: {
- limit,
- offset
- }
- });
- }
-
- /**
- *
Use this call to update non-physical location details for an existing inventory location.
- * @param merchantLocationKey A unique merchant-defined key (ID) for an inventory location.
- * @param body The inventory location details to be updated (other than the address and geo co-ordinates).
- */
- public updateInventoryLocation(merchantLocationKey: string, body: InventoryLocation) {
- merchantLocationKey = encodeURIComponent(merchantLocationKey);
- return this.post(`/location/${merchantLocationKey}/update_location_details`, body);
- }
-
- /**
- * This method retrieves all the sales tax jurisdictions for the country that you specify in the countryCode path parameter.
- * @param countryCode This path parameter specifies the two-letter ISO 3166 country code for the country whose jurisdictions you want to retrieve. eBay provides sales tax jurisdiction information for Canada and the United States.
- */
- public getSalesTaxJurisdictions(countryCode: string) {
- countryCode = encodeURIComponent(countryCode);
- return this.get(`/country/${countryCode}/sales_tax_jurisdiction`);
- }
-
}
diff --git a/src/api/restful/sell/account/v2.ts b/src/api/restful/sell/account/v2.ts
index 6a0bc234..c61da73f 100644
--- a/src/api/restful/sell/account/v2.ts
+++ b/src/api/restful/sell/account/v2.ts
@@ -1,4 +1,15 @@
-import {RateTableUpdate, UpdatePayoutPercentageRequest} from '../../../../types/index.js';
+import {
+ CreateCalculatedShippingRulesRequest,
+ CreateFlatShippingRulesRequest,
+ CreatePromotionalShippingRuleRequest,
+ RateTableUpdate,
+ SetUserPreferencesRequest,
+ UpdateCalculatedShippingRulesRequest,
+ UpdateCombinedPaymentsRequest,
+ UpdateFlatShippingRulesRequest,
+ UpdatePayoutPercentageRequest,
+ UpdatePromotionalShippingRuleRequest
+} from '../../../../types/index.js';
import {operations} from '../../../../types/restful/specs/sell_account_v2_oas3.js';
import Restful, {OpenApi} from '../../index.js';
@@ -46,4 +57,87 @@ export default class AccountV2 extends Restful implements OpenApi {
public updatePayoutPercentage(body: UpdatePayoutPercentageRequest) {
return this.post('/payout_settings/update_percentage', body);
}
+
+ /**
+ * This method retrieves the combined shipping rules configured on the seller's account.
+ */
+ public getCombinedShippingRules() {
+ return this.get('/combined_shipping_rules');
+ }
+
+ /**
+ * This method creates calculated combined shipping rules for the seller's account.
+ * @param body This request payload contains the calculated shipping rules to create.
+ */
+ public createCalculatedShippingRules(body?: CreateCalculatedShippingRulesRequest) {
+ return this.post('/combined_shipping_rules/create_calculated_shipping_rules', body);
+ }
+
+ /**
+ * This method creates flat-rate combined shipping rules for the seller's account.
+ * @param body This request payload contains the flat shipping rules to create.
+ */
+ public createFlatShippingRules(body?: CreateFlatShippingRulesRequest) {
+ return this.post('/combined_shipping_rules/create_flat_shipping_rules', body);
+ }
+
+ /**
+ * This method creates a promotional combined shipping rule for the seller's account.
+ * @param body This request payload contains the promotional shipping rule to create.
+ */
+ public createPromotionalShippingRule(body?: CreatePromotionalShippingRuleRequest) {
+ return this.post('/combined_shipping_rules/create_promotional_shipping_rule', body);
+ }
+
+ /**
+ * This method updates the calculated combined shipping rules for the seller's account.
+ * @param body This request payload contains the calculated shipping rules to update.
+ */
+ public updateCalculatedShippingRules(body?: UpdateCalculatedShippingRulesRequest) {
+ return this.post('/combined_shipping_rules/update_calculated_shipping_rules', body);
+ }
+
+ /**
+ * This method updates the combined payments settings for the seller's account.
+ * @param body This request payload contains the combined payments settings to update.
+ */
+ public updateCombinedPayments(body?: UpdateCombinedPaymentsRequest) {
+ return this.post('/combined_shipping_rules/update_combined_payments', body);
+ }
+
+ /**
+ * This method updates the flat-rate combined shipping rules for the seller's account.
+ * @param body This request payload contains the flat shipping rules to update.
+ */
+ public updateFlatShippingRules(body?: UpdateFlatShippingRulesRequest) {
+ return this.post('/combined_shipping_rules/update_flat_shipping_rules', body);
+ }
+
+ /**
+ * This method updates a promotional combined shipping rule for the seller's account.
+ * @param body This request payload contains the promotional shipping rule to update.
+ */
+ public updatePromotionalShippingRule(body?: UpdatePromotionalShippingRuleRequest) {
+ return this.post('/combined_shipping_rules/update_promotional_shipping_rule', body);
+ }
+
+ /**
+ * This method retrieves the seller's preferences for the specified marketplace.
+ * @param fieldgroups This query parameter specifies the preference groups to return.
+ */
+ public getUserPreferences(fieldgroups?: string) {
+ return this.get('/user_preferences', {
+ params: {
+ fieldgroups
+ }
+ });
+ }
+
+ /**
+ * This method configures the seller's preferences for the specified marketplace.
+ * @param body This request payload contains the seller preferences to set.
+ */
+ public setUserPreferences(body?: SetUserPreferencesRequest) {
+ return this.patch('/user_preferences', body);
+ }
}
diff --git a/src/api/restful/sell/compliance/index.ts b/src/api/restful/sell/compliance/index.ts
deleted file mode 100644
index 26c98297..00000000
--- a/src/api/restful/sell/compliance/index.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-import {SuppressViolationRequest} from '../../../../types/index.js';
-import {operations} from '../../../../types/restful/specs/sell_compliance_v1_oas3.js';
-import Restful, {OpenApi} from '../../index.js';
-
-/**
- * Service for providing the compliance violations of seller account/listings
- */
-export default class Compliance extends Restful implements OpenApi {
-
- static id = 'Compliance';
-
- get basePath(): string {
- return '/sell/compliance/v1';
- }
-
- /**
- * This call returns listing violation counts for a seller.
- *
- * @param complianceType A user passes in one or more compliance type values through this query parameter.
- */
- public getListingViolationsSummary(complianceType?: string) {
- return this.get('/listing_violation_summary', {
- params: {
- compliance_type: complianceType
- }
- });
- }
-
- /**
- * This call returns specific listing violations for five different compliance types.
- *
- * @param complianceType A user passes in one or more compliance type values through this query parameter.
- * @param offset The first policy violation to return based on its position in the collection of listing
- * violations.
- * @param listingId
- * @param limit This query parameter is used if the user wants to set a limit on the number of listing violations
- * that are returned in the current result set.
- */
- public getListingViolations({complianceType, offset, listingId, limit}:
- { complianceType?: string, offset?: number, listingId?: string, limit?: number } = {}) {
- return this.get('/listing_violation', {
- params: {
- compliance_type: complianceType,
- offset,
- listing_id: listingId,
- limit
- }
- });
- }
-
- /**
- * This call suppresses a listing violation for a specific listing. Only listing violations in the AT_RISK state (returned in the violations.complianceState field of the getListingViolations call) can be suppressed.
- *
- * @param body SuppressViolationRequest
- */
- public suppressViolation(body: SuppressViolationRequest) {
- return this.post('/suppress_listing_violation', body);
- }
-}
diff --git a/src/api/restful/sell/feed/index.ts b/src/api/restful/sell/feed/index.ts
index 52c251ce..c236cb44 100644
--- a/src/api/restful/sell/feed/index.ts
+++ b/src/api/restful/sell/feed/index.ts
@@ -1,5 +1,13 @@
import {multipartHeader} from '../../../../request.js';
-import {SellFeedParams} from '../../../../types/index.js';
+import {
+ SellFeedParams,
+ CreateOrderTaskRequest,
+ CreateInventoryTaskRequest,
+ CreateUserScheduleRequest,
+ UpdateUserScheduleRequest,
+ CreateTaskRequest,
+ CreateServiceMetricsTaskRequest
+} from '../../../../types/index.js';
import {operations} from '../../../../types/restful/specs/sell_feed_v1_oas3.js';
import Restful, {OpenApi} from '../../index.js';
@@ -49,7 +57,7 @@ export default class Feed extends Restful implements OpenApi {
*
* @param data The CreateOrderTaskRequest
*/
- public createOrderTask(data: any) {
+ public createOrderTask(data: CreateOrderTaskRequest) {
return this.post('/order_task', data);
}
@@ -91,7 +99,7 @@ export default class Feed extends Restful implements OpenApi {
/**
* This method creates an inventory-related download task for a specified feed type with optional filter criteria.
*/
- public createInventoryTask(data: any) {
+ public createInventoryTask(data: CreateInventoryTaskRequest) {
return this.post('/inventory_task', data);
}
@@ -130,7 +138,7 @@ export default class Feed extends Restful implements OpenApi {
*
* @params data The CreateUserScheduleRequest
*/
- public createSchedule(data: any) {
+ public createSchedule(data: CreateUserScheduleRequest) {
return this.post('/schedule', data);
}
@@ -150,7 +158,7 @@ export default class Feed extends Restful implements OpenApi {
* @param scheduleId The ID of the schedule to update.
* @param data The UpdateUserScheduleRequest.
*/
- public updateSchedule(scheduleId: string, data?: any) {
+ public updateSchedule(scheduleId: string, data?: UpdateUserScheduleRequest) {
scheduleId = encodeURIComponent(scheduleId);
return this.put(`/schedule/${scheduleId}`, data);
}
@@ -244,7 +252,7 @@ export default class Feed extends Restful implements OpenApi {
*
* @param data The CreateTaskRequest.
*/
- public createTask(data: any) {
+ public createTask(data: CreateTaskRequest) {
return this.post('/task', data);
}
@@ -328,7 +336,7 @@ export default class Feed extends Restful implements OpenApi {
* @params acceptLanguage Use this header to specify the natural language in which the authenticated user desires the response.
* @params data The CreateServiceMetricsTaskRequest
*/
- public createCustomerServiceMetricTask(acceptLanguage: string, data: any) {
+ public createCustomerServiceMetricTask(acceptLanguage: string, data: CreateServiceMetricsTaskRequest) {
return this.post('/customer_service_metric_task', data, {
headers: {
'accept-language': acceptLanguage
diff --git a/src/api/restful/sell/finances/index.ts b/src/api/restful/sell/finances/index.ts
index 37a63a08..1a1ad78c 100644
--- a/src/api/restful/sell/finances/index.ts
+++ b/src/api/restful/sell/finances/index.ts
@@ -1,4 +1,5 @@
import {operations} from '../../../../types/restful/specs/sell_finances_v1_oas3.js';
+import {toFilter} from '../../../../utils/params.js';
import Restful, {OpenApi} from '../../index.js';
/**
@@ -46,14 +47,14 @@ export default class Finances extends Restful implements OpenApi {
offset,
sort
}: {
- filter?: string;
+ filter?: string | string[];
limit?: number;
offset?: number;
sort?: 'payoutDate' | '-payoutDate';
} = {}) {
return this.get('/payout', {
params: {
- filter,
+ filter: toFilter(filter),
limit,
offset,
sort
@@ -70,9 +71,9 @@ export default class Finances extends Restful implements OpenApi {
public getPayoutSummary({
filter
}: {
- filter?: string;
+ filter?: string | string[];
} = {}) {
- return this.get('/payout_summary', {params: {filter}});
+ return this.get('/payout_summary', {params: {filter: toFilter(filter)}});
}
/**
@@ -90,14 +91,14 @@ export default class Finances extends Restful implements OpenApi {
offset,
sort
}: {
- filter?: string;
+ filter?: string | string[];
limit?: number;
offset?: number;
sort?: 'transactionDate' | '-transactionDate',
} = {}) {
return this.get('/transaction', {
params: {
- filter,
+ filter: toFilter(filter),
limit,
offset,
sort
@@ -114,11 +115,11 @@ export default class Finances extends Restful implements OpenApi {
public getTransactionSummary({
filter
}: {
- filter?: string;
+ filter?: string | string[];
} = {}) {
return this.get('/transaction_summary', {
params: {
- filter
+ filter: toFilter(filter)
}
});
}
@@ -139,4 +140,77 @@ export default class Finances extends Restful implements OpenApi {
public getSellerFundsSummary() {
return this.get('/seller_funds_summary');
}
+
+ /**
+ * This method retrieves the total earnings of the seller's orders.
+ *
+ * @param filter One or more comma-separated criteria for narrowing down the collection of order earnings returned.
+ * @param limit The number of order earnings to return per page of the result set.
+ * @param offset The number of order earnings to skip in the result set before returning the first order earning.
+ * @param sort Sorts the returned order earnings.
+ */
+ public getOrderEarnings({filter, limit, offset, sort}: {
+ filter?: string | string[];
+ limit?: number;
+ offset?: number;
+ sort?: string;
+ } = {}) {
+ return this.get('/order_earnings', {
+ params: {
+ filter: toFilter(filter),
+ limit,
+ offset,
+ sort
+ }
+ });
+ }
+
+ /**
+ * This method retrieves the earnings of a specific order.
+ *
+ * @param orderId The unique identifier of the order.
+ */
+ public getOrderEarningsById(orderId: string) {
+ orderId = encodeURIComponent(orderId);
+ return this.get(`/order_earnings/${orderId}`);
+ }
+
+ /**
+ * This method retrieves a summary of the total earnings of the seller's orders.
+ *
+ * @param filter One or more comma-separated criteria for narrowing down the order earnings included in the summary.
+ */
+ public getOrderEarningsSummary({filter}: {
+ filter?: string | string[];
+ } = {}) {
+ return this.get('/order_earnings_summary', {
+ params: {
+ filter: toFilter(filter)
+ }
+ });
+ }
+
+ /**
+ * This method retrieves a seller's billing activity.
+ *
+ * @param filter One or more comma-separated criteria for narrowing down the collection of billing activities returned.
+ * @param limit The number of billing activities to return per page of the result set.
+ * @param offset The number of billing activities to skip in the result set before returning the first activity.
+ * @param sort Sorts the returned billing activities.
+ */
+ public getBillingActivities({filter, limit, offset, sort}: {
+ filter?: string | string[];
+ limit?: number;
+ offset?: number;
+ sort?: string;
+ } = {}) {
+ return this.get('/billing_activity', {
+ params: {
+ filter: toFilter(filter),
+ limit,
+ offset,
+ sort
+ }
+ });
+ }
}
diff --git a/src/api/restful/sell/index.ts b/src/api/restful/sell/index.ts
index b8af09c3..36ea7aa1 100644
--- a/src/api/restful/sell/index.ts
+++ b/src/api/restful/sell/index.ts
@@ -1,7 +1,6 @@
import AccountV1 from './account/v1.js';
import AccountV2 from './account/v2.js';
import Analytics from './analytics/index.js';
-import Compliance from './compliance/index.js';
import Finances from './finances/index.js';
import Fulfillment from './fulfillment/index.js';
import Inventory from './inventory/index.js';
@@ -12,12 +11,12 @@ import Feed from './feed/index.js';
import Logistics from './logistics/index.js';
import Negotiation from './negotiation/index.js';
import Listing from './listing/index.js';
+import Stores from './stores/index.js';
export type Sell = {
account: AccountV1,
accountV2: AccountV2,
analytics: Analytics,
- compliance: Compliance,
fulfillment: Fulfillment,
inventory: Inventory,
marketing: Marketing,
@@ -27,13 +26,13 @@ export type Sell = {
feed: Feed,
logistics: Logistics,
negotiation: Negotiation,
- listing: Listing
+ listing: Listing,
+ stores: Stores
};
export {
AccountV1,
AccountV2,
- Compliance,
Analytics,
Fulfillment,
Inventory,
@@ -44,5 +43,6 @@ export {
Feed,
Logistics,
Negotiation,
- Listing
+ Listing,
+ Stores
};
diff --git a/src/api/restful/sell/listing/index.ts b/src/api/restful/sell/listing/index.ts
index fae4901b..33ac6be7 100644
--- a/src/api/restful/sell/listing/index.ts
+++ b/src/api/restful/sell/listing/index.ts
@@ -1,3 +1,4 @@
+import {ItemDraft} from '../../../../types/index.js';
import {operations} from '../../../../types/restful/specs/sell_listing_v1_beta_oas3.js';
import Restful, {OpenApi} from '../../index.js';
@@ -17,7 +18,7 @@ export default class Listing extends Restful implements OpenApi {
*
* @param data The ItemDraft
*/
- public createItemDraft(data?: any) {
+ public createItemDraft(data?: ItemDraft) {
return this.post('/item_draft/', data);
}
diff --git a/src/api/restful/sell/logistics/index.ts b/src/api/restful/sell/logistics/index.ts
index 5be70134..16b3ac7c 100644
--- a/src/api/restful/sell/logistics/index.ts
+++ b/src/api/restful/sell/logistics/index.ts
@@ -1,3 +1,7 @@
+import {
+ ShippingQuoteRequest,
+ CreateShipmentFromQuoteRequest
+} from '../../../../types/index.js';
import {operations} from '../../../../types/restful/specs/sell_logistics_v1_oas3.js';
import Restful, {OpenApi} from '../../index.js';
@@ -17,7 +21,7 @@ export default class Logistics extends Restful implements OpenApi {
*
* @param data The ShippingQuoteRequest
*/
- public createShippingQuote(data: any) {
+ public createShippingQuote(data: ShippingQuoteRequest) {
return this.post('/shipping_quote', data);
}
@@ -36,7 +40,7 @@ export default class Logistics extends Restful implements OpenApi {
*
* @param data The CreateShipmentFromQuoteRequest
*/
- public createFromShippingQuote(data: any) {
+ public createFromShippingQuote(data: CreateShipmentFromQuoteRequest) {
return this.post('/shipment/create_from_shipping_quote', data);
}
@@ -45,7 +49,8 @@ export default class Logistics extends Restful implements OpenApi {
*
* @param shipmentId This path parameter specifies the unique eBay-assigned ID of the shipment you want to retrieve.
*/
- public getShipment(shipmentId: any) {
+ public getShipment(shipmentId: string) {
+ shipmentId = encodeURIComponent(shipmentId);
return this.get(`/shipment/${shipmentId}`);
}
@@ -54,8 +59,14 @@ export default class Logistics extends Restful implements OpenApi {
*
* @param shipmentId This path parameter specifies the unique eBay-assigned ID of the shipment associated with the shipping label you want to download.
*/
- public downloadLabelFile(shipmentId: any) {
- return this.get(`/shipment/${shipmentId}/download_label_file`);
+ public downloadLabelFile(shipmentId: string) {
+ shipmentId = encodeURIComponent(shipmentId);
+ return this.get(`/shipment/${shipmentId}/download_label_file`, {
+ responseType: 'arraybuffer',
+ headers: {
+ Accept: 'application/pdf'
+ }
+ });
}
/**
@@ -63,7 +74,8 @@ export default class Logistics extends Restful implements OpenApi {
*
* @param shipmentId This path parameter specifies the unique eBay-assigned ID of the shipment to be canceled.
*/
- public cancelShipment(shipmentId: any) {
+ public cancelShipment(shipmentId: string) {
+ shipmentId = encodeURIComponent(shipmentId);
return this.post(`/shipment/${shipmentId}/cancel`);
}
}
diff --git a/src/api/restful/sell/marketing/index.ts b/src/api/restful/sell/marketing/index.ts
index 87f5fe4f..0dced1d5 100644
--- a/src/api/restful/sell/marketing/index.ts
+++ b/src/api/restful/sell/marketing/index.ts
@@ -20,7 +20,6 @@ import {
CreateReportTask,
ItemPriceMarkdown,
ItemPromotion,
- QuickSetupRequest,
TargetedBidRequest,
TargetedKeywordRequest,
UpdateAdGroupRequest,
@@ -30,7 +29,9 @@ import {
UpdateCampaignIdentificationRequest,
UpdateCampaignRequest,
UpdateKeywordRequest,
- UpdateNegativeKeywordRequest
+ UpdateNegativeKeywordRequest,
+ SuggestMaxCpcRequest,
+ UpdateBiddingStrategyRequest
} from '../../../../types/index.js';
import {operations} from '../../../../types/restful/specs/sell_marketing_v1_oas3.js';
import Restful, {OpenApi} from '../../index.js';
@@ -150,23 +151,6 @@ export default class Marketing extends Restful implements OpenApi {
return this.post(`/ad_campaign/${campaignId}/bulk_update_ads_status_by_listing_id`, body);
}
- /**
- * This method launches a Promoted Listings Advanced campaign.
- * @param campaignId teh campaign id
- */
- public launchCampaign(campaignId: string) {
- campaignId = encodeURIComponent(campaignId);
- return this.post(`/ad_campaign/${campaignId}/launch`);
- }
-
- /**
- * This method allows the seller to expedite the creation of a Promoted Listings Advanced (PLA) campaign.
- * @param body This type defines the fields to create a quick setup Promoted Listings Advanced (PLA) campaign.
- */
- public setupQuickCampaign(body: QuickSetupRequest) {
- return this.post('/ad_campaign/setup_quick_campaign', body);
- }
-
/**
* This method retrieves all the ads for the specified campaign.
*
@@ -1113,4 +1097,29 @@ export default class Marketing extends Restful implements OpenApi {
});
}
+ /**
+ * This method allows sellers to retrieve the suggested budget for an offsite campaign.
+ */
+ public suggestBudget() {
+ return this.get('/ad_campaign/suggest_budget');
+ }
+
+ /**
+ * This method allows sellers to retrieve the suggested maximum cost-per-click value for a smart targeting campaign.
+ * @param body The request to suggest max CPC
+ */
+ public suggestMaxCpc(body?: SuggestMaxCpcRequest) {
+ return this.post('/ad_campaign/suggest_max_cpc', body);
+ }
+
+ /**
+ * This method allows sellers to change the bidding strategy for a specified Cost Per Click (CPC) campaign.
+ * @param campaignId A unique eBay-assigned ID for an ad campaign
+ * @param body The bidding strategy update request
+ */
+ public updateBiddingStrategy(campaignId: string, body?: UpdateBiddingStrategyRequest) {
+ campaignId = encodeURIComponent(campaignId);
+ return this.post(`/ad_campaign/${campaignId}/update_bidding_strategy`, body);
+ }
+
}
diff --git a/src/api/restful/sell/metadata/index.ts b/src/api/restful/sell/metadata/index.ts
index 6c65f559..77aeea3a 100644
--- a/src/api/restful/sell/metadata/index.ts
+++ b/src/api/restful/sell/metadata/index.ts
@@ -1,3 +1,10 @@
+import {
+ SpecificationRequest,
+ PropertyNamesRequest,
+ PropertyValuesRequest,
+ MultiCompatibilityPropertyValuesRequest,
+ ProductRequest
+} from '../../../../types/index.js';
import {operations} from '../../../../types/restful/specs/sell_metadata_v1_oas3.js';
import Restful, {OpenApi} from '../../index.js';
@@ -114,24 +121,6 @@ export default class Metadata extends Restful implements OpenApi {
});
}
- /**
- * This method retrieves a list of leaf categories for a marketplace and identifies the categories that require
- * items to have an eBay product ID value in order to be listed in those categories.
- *
- * @param marketplaceId This path parameter specifies the eBay marketplace for which policy information is
- * retrieved.
- * @param filter This query parameter limits the response by returning eBay policy information for only the leaf
- * categories specified by this parameter.
- */
- public getProductAdoptionPolicies(marketplaceId: string, filter?: string) {
- marketplaceId = encodeURIComponent(marketplaceId);
- return this.get(`/marketplace/${marketplaceId}/get_product_adoption_policies`, {
- params: {
- filter
- }
- });
- }
-
/**
* This method returns the eBay policies that define whether or not you must include a return policy for the
* items you list in the categories of a specific marketplace, plus the guidelines for creating domestic and
@@ -165,4 +154,191 @@ export default class Metadata extends Restful implements OpenApi {
marketplaceId = encodeURIComponent(marketplaceId);
return this.get(`/marketplace/${marketplaceId}/get_hazardous_materials_labels`);
}
+
+ /**
+ * This method returns category policies for the specified marketplace.
+ * @param marketplaceId The eBay marketplace ID
+ * @param filter Filter for specific categories
+ */
+ public getCategoryPolicies(marketplaceId: string, filter?: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/marketplace/${marketplaceId}/get_category_policies`, {
+ params: { filter }
+ });
+ }
+
+ /**
+ * This method returns classified ad policies for the specified marketplace.
+ * @param marketplaceId The eBay marketplace ID
+ * @param filter Filter for specific categories
+ */
+ public getClassifiedAdPolicies(marketplaceId: string, filter?: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/marketplace/${marketplaceId}/get_classified_ad_policies`, {
+ params: { filter }
+ });
+ }
+
+ /**
+ * This method returns the currencies available for the specified marketplace.
+ * @param marketplaceId The eBay marketplace ID
+ */
+ public getCurrencies(marketplaceId: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/marketplace/${marketplaceId}/get_currencies`);
+ }
+
+ /**
+ * This method returns listing type policies for the specified marketplace.
+ * @param marketplaceId The eBay marketplace ID
+ * @param filter Filter for specific categories
+ */
+ public getListingTypePolicies(marketplaceId: string, filter?: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/marketplace/${marketplaceId}/get_listing_type_policies`, {
+ params: { filter }
+ });
+ }
+
+ /**
+ * This method returns motors listing policies for the specified marketplace.
+ * @param marketplaceId The eBay marketplace ID
+ * @param filter Filter for specific categories
+ */
+ public getMotorsListingPolicies(marketplaceId: string, filter?: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/marketplace/${marketplaceId}/get_motors_listing_policies`, {
+ params: { filter }
+ });
+ }
+
+ /**
+ * This method returns product safety labels for the specified marketplace.
+ * @param marketplaceId The eBay marketplace ID
+ */
+ public getProductSafetyLabels(marketplaceId: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/marketplace/${marketplaceId}/get_product_safety_labels`);
+ }
+
+ /**
+ * This method returns regulatory policies for the specified marketplace.
+ * @param marketplaceId The eBay marketplace ID
+ * @param filter Filter for specific categories
+ */
+ public getRegulatoryPolicies(marketplaceId: string, filter?: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/marketplace/${marketplaceId}/get_regulatory_policies`, {
+ params: { filter }
+ });
+ }
+
+ /**
+ * This method returns shipping policies for the specified marketplace.
+ * @param marketplaceId The eBay marketplace ID
+ * @param filter Filter for specific categories
+ */
+ public getShippingPolicies(marketplaceId: string, filter?: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/marketplace/${marketplaceId}/get_shipping_policies`, {
+ params: { filter }
+ });
+ }
+
+ /**
+ * This method returns site visibility policies for the specified marketplace.
+ * @param marketplaceId The eBay marketplace ID
+ * @param filter Filter for specific categories
+ */
+ public getSiteVisibilityPolicies(marketplaceId: string, filter?: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/marketplace/${marketplaceId}/get_site_visibility_policies`, {
+ params: { filter }
+ });
+ }
+
+ /**
+ * This method returns compatibilities by specification.
+ * @param body The specification request
+ */
+ public getCompatibilitiesBySpecification(body?: SpecificationRequest) {
+ return this.post('/compatibilities/get_compatibilities_by_specification', body);
+ }
+
+ /**
+ * This method returns compatibility property names.
+ * @param body The property names request
+ */
+ public getCompatibilityPropertyNames(body?: PropertyNamesRequest) {
+ return this.post('/compatibilities/get_compatibility_property_names', body);
+ }
+
+ /**
+ * This method returns compatibility property values.
+ * @param body The property values request
+ */
+ public getCompatibilityPropertyValues(body?: PropertyValuesRequest) {
+ return this.post('/compatibilities/get_compatibility_property_values', body);
+ }
+
+ /**
+ * This method returns multiple compatibility property values.
+ * @param body The multi property values request
+ */
+ public getMultiCompatibilityPropertyValues(body?: MultiCompatibilityPropertyValuesRequest) {
+ return this.post('/compatibilities/get_multi_compatibility_property_values', body);
+ }
+
+ /**
+ * This method returns product compatibilities.
+ * @param body The product compatibilities request
+ */
+ public getProductCompatibilities(body?: ProductRequest) {
+ return this.post('/compatibilities/get_product_compatibilities', body);
+ }
+
+ /**
+ * This method returns the excluded shipping locations for the specified marketplace.
+ * @param marketplaceId The eBay marketplace for which the excluded shipping locations are retrieved.
+ */
+ public getExcludeShippingLocations(marketplaceId: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/shipping/marketplace/${marketplaceId}/get_exclude_shipping_locations`);
+ }
+
+ /**
+ * This method returns the handling times for the specified marketplace.
+ * @param marketplaceId The eBay marketplace for which the handling times are retrieved.
+ */
+ public getHandlingTimes(marketplaceId: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/shipping/marketplace/${marketplaceId}/get_handling_times`);
+ }
+
+ /**
+ * This method returns the shipping carriers supported for the specified marketplace.
+ * @param marketplaceId The eBay marketplace for which the shipping carriers are retrieved.
+ */
+ public getShippingCarriers(marketplaceId: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/shipping/marketplace/${marketplaceId}/get_shipping_carriers`);
+ }
+
+ /**
+ * This method returns the shipping locations supported for the specified marketplace.
+ * @param marketplaceId The eBay marketplace for which the shipping locations are retrieved.
+ */
+ public getShippingLocations(marketplaceId: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/shipping/marketplace/${marketplaceId}/get_shipping_locations`);
+ }
+
+ /**
+ * This method returns the shipping services supported for the specified marketplace.
+ * @param marketplaceId The eBay marketplace for which the shipping services are retrieved.
+ */
+ public getShippingServices(marketplaceId: string) {
+ marketplaceId = encodeURIComponent(marketplaceId);
+ return this.get(`/shipping/marketplace/${marketplaceId}/get_shipping_services`);
+ }
}
diff --git a/src/api/restful/sell/negotiation/index.ts b/src/api/restful/sell/negotiation/index.ts
index 7421f4d8..b99496e9 100644
--- a/src/api/restful/sell/negotiation/index.ts
+++ b/src/api/restful/sell/negotiation/index.ts
@@ -1,3 +1,4 @@
+import {CreateOffersRequest} from '../../../../types/index.js';
import {operations} from '../../../../types/restful/specs/sell_negotiation_v1_oas3.js';
import Restful, {OpenApi} from '../../index.js';
@@ -32,7 +33,7 @@ export default class Negotiation extends Restful implements OpenApi
*
* @param data The CreateOffersRequest
*/
- public sendOfferToInterestedBuyers(data: any) {
+ public sendOfferToInterestedBuyers(data: CreateOffersRequest) {
return this.post('/send_offer_to_interested_buyers', data);
}
}
diff --git a/src/api/restful/sell/stores/index.ts b/src/api/restful/sell/stores/index.ts
new file mode 100644
index 00000000..2b7cfbee
--- /dev/null
+++ b/src/api/restful/sell/stores/index.ts
@@ -0,0 +1,93 @@
+import {
+ AddStoreCategoryRequest,
+ DeleteStoreCategoryRequest,
+ MoveStoreCategoryRequest,
+ RenameStoreCategoryRequest
+} from '../../../../types/index.js';
+import {operations} from '../../../../types/restful/specs/sell_stores_v1_oas3.js';
+import Restful, {OpenApi} from '../../index.js';
+
+/**
+ * The Store API allows sellers to retrieve and manage the categories of their eBay store.
+ */
+export default class Stores extends Restful implements OpenApi {
+
+ static id = 'Stores';
+
+ get basePath(): string {
+ return '/sell/stores/v1';
+ }
+
+ /**
+ * This method retrieves the details of an eBay store.
+ */
+ public getStore() {
+ return this.get('/store');
+ }
+
+ /**
+ * This method retrieves the category tree of a seller's eBay store.
+ */
+ public getStoreCategories() {
+ return this.get('/store/categories');
+ }
+
+ /**
+ * This method adds a single new category to a seller's eBay store.
+ *
+ * @param body The container for the category to be added to the seller's eBay store.
+ */
+ public addStoreCategory(body?: AddStoreCategoryRequest) {
+ return this.post('/store/categories', body);
+ }
+
+ /**
+ * This method renames a single existing category of a seller's eBay store.
+ *
+ * @param categoryId The unique identifier of the eBay store category to be renamed.
+ * @param body The container with the new name of the eBay store category.
+ */
+ public renameStoreCategory(categoryId: string, body?: RenameStoreCategoryRequest) {
+ categoryId = encodeURIComponent(categoryId);
+ return this.put(`/store/categories/${categoryId}`, body);
+ }
+
+ /**
+ * This method deletes a single existing category of a seller's eBay store.
+ *
+ * @param categoryId The unique identifier of the eBay store category to be deleted.
+ * @param body The container specifying where to move any listings and child categories of the deleted category.
+ */
+ public deleteStoreCategory(categoryId: string, body?: DeleteStoreCategoryRequest) {
+ categoryId = encodeURIComponent(categoryId);
+ return this.delete(`/store/categories/${categoryId}`, {data: body});
+ }
+
+ /**
+ * This method moves a single existing category of a seller's eBay store. This operation is
+ * asynchronous; a successful call returns the getStoreTask URI in the Location response
+ * header, which the seller calls to retrieve the status of the move operation.
+ *
+ * @param body The container specifying the category to move and its destination.
+ */
+ public moveStoreCategory(body: MoveStoreCategoryRequest) {
+ return this.post('/store/categories/move_category', body);
+ }
+
+ /**
+ * This method retrieves the details and status of a single eBay store task.
+ *
+ * @param taskId The unique identifier of the eBay store task to retrieve.
+ */
+ public getStoreTask(taskId: string) {
+ taskId = encodeURIComponent(taskId);
+ return this.get(`/store/tasks/${taskId}`);
+ }
+
+ /**
+ * This method retrieves the details and status of a seller's eBay store tasks.
+ */
+ public getStoreTasks() {
+ return this.get('/store/tasks');
+ }
+}
diff --git a/src/api/traditional/finding/index.ts b/src/api/traditional/finding/index.ts
deleted file mode 100644
index e7051651..00000000
--- a/src/api/traditional/finding/index.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-enum calls {
- findCompletedItems,
- findItemsAdvanced,
- findItemsByCategory,
- findItemsByKeywords,
- findItemsByProduct,
- findItemsIneBayStores,
- getHistograms,
- getSearchKeywordsRecommendation,
- getVersion
-}
-
-export default calls;
diff --git a/src/api/traditional/index.ts b/src/api/traditional/index.ts
index 8a80577c..e80c807d 100644
--- a/src/api/traditional/index.ts
+++ b/src/api/traditional/index.ts
@@ -6,11 +6,10 @@ import {
EBayIAFTokenInvalid,
handleEBayError
} from '../../errors/index.js';
-import {ClientAlerts, Finding, Merchandising, Shopping, Trading, TraditionalApi} from '../../types/index.js';
+import {ClientAlerts, Merchandising, Shopping, Trading, TraditionalApi} from '../../types/index.js';
import Api from '../index.js';
import ClientAlertsCalls from './clientAlerts/index.js';
import {Fields} from './fields.js';
-import FindingCalls from './finding/index.js';
import MerchandisingCalls from './merchandising/index.js';
import ShoppingCalls from './shopping/index.js';
import TradingCalls from './trading/index.js';
@@ -68,22 +67,6 @@ export default class Traditional extends Api {
});
}
- public createFindingApi(): Finding {
- return this.createTraditionalXMLApi({
- endpoint: {
- production: 'svcs.ebay.com',
- sandbox: 'svcs.sandbox.ebay.com'
- },
- path: '/services/search/FindingService/v1',
- xmlns: 'http://www.ebay.com/marketplace/search/v1/services',
- calls: FindingCalls,
- headers: (callName: string) => ({
- 'X-EBAY-SOA-SECURITY-APPNAME': this.config.appId,
- 'X-EBAY-SOA-OPERATION-NAME': callName
- })
- });
- }
-
public createClientAlertsApi(): ClientAlerts {
if (typeof this.config.siteId !== 'number') {
throw new Error('siteId is required for client alerts API.');
diff --git a/src/eBayApi.ts b/src/eBayApi.ts
index 9e45ebeb..e2779cff 100644
--- a/src/eBayApi.ts
+++ b/src/eBayApi.ts
@@ -13,7 +13,7 @@ import * as errors from './errors/index.js';
import {ApiEnvError} from './errors/index.js';
import {IEBayApiRequest} from './request.js';
import * as types from './types/index.js';
-import {AppConfig, ClientAlerts, Finding, Keyset, Merchandising, Shopping, Signature, Trading} from './types/index.js';
+import {AppConfig, ClientAlerts, Keyset, Merchandising, Shopping, Signature, Trading} from './types/index.js';
const defaultConfig: Omit = {
sandbox: false,
@@ -85,7 +85,6 @@ export default class eBayApi extends Api {
// Traditional API
private _trading?: Trading;
- private _finding?: Finding;
private _shopping?: Shopping;
private _merchandising?: Merchandising;
@@ -131,10 +130,6 @@ export default class eBayApi extends Api {
return this._trading || (this._trading = this.factory.createTradingApi());
}
- get finding(): Finding {
- return this._finding || (this._finding = this.factory.createFindingApi());
- }
-
get shopping(): Shopping {
return this._shopping || (this._shopping = this.factory.createShoppingApi());
}
diff --git a/src/request.ts b/src/request.ts
index f05e176f..1581100a 100644
--- a/src/request.ts
+++ b/src/request.ts
@@ -14,6 +14,10 @@ export const multipartHeader = {
'Content-Type': 'multipart/form-data'
}
+export const octetStreamHeader = {
+ 'Content-Type': 'application/octet-stream'
+}
+
export const defaultAxiosConfig: AxiosRequestConfig = {
paramsSerializer: {
indexes: null
@@ -32,6 +36,8 @@ export interface IEBayApiRequest;
put(url: string, data?: any, config?: C): Promise;
+
+ patch(url: string, data?: any, config?: C): Promise;
}
export class AxiosRequest implements IEBayApiRequest {
@@ -67,6 +73,11 @@ export class AxiosRequest implements IEBayApiRequest {
return this.instance.put(url, payload, config);
}
+ public patch(url: string, payload?: any, config?: AxiosRequestConfig): Promise {
+ log('patch: ' + url, {payload, config});
+ return this.instance.patch(url, payload, config);
+ }
+
public postForm(url: string, payload?: any, config?: AxiosRequestConfig): Promise {
log('postForm: ' + url);
const body = stringify(payload);
diff --git a/src/types/restful/specs/buy_browse_v1_oas3.ts b/src/types/restful/specs/buy_browse_v1_oas3.ts
index d179ed5d..975a7034 100644
--- a/src/types/restful/specs/buy_browse_v1_oas3.ts
+++ b/src/types/restful/specs/buy_browse_v1_oas3.ts
@@ -11,7 +11,7 @@ export interface paths {
path?: never;
cookie?: never;
};
- /** @description This method searches for eBay items by various query parameters and retrieves summaries of the items. You can search by keyword, category, eBay product ID (ePID), or GTIN, charity ID, or a combination of these.
Note: Only FIXED_PRICE (Buy It Now) items are returned by default. However, this method does return items where both FIXED_PRICE and AUCTION are available as a buying option. After a bid has been placed, items become active auction items and are no longer returned by default, but they remain accessible by filtering for the AUCTION buying option.
This method also supports the following:
- Filtering by the value of one or multiple fields, such as listing format, item condition, price range, location, and more. For the fields supported by this method, see the filter parameter.
- Retrieving the refinements (metadata) of an item , such as item aspects (color, brand), condition, category, etc. using the fieldgroups parameter.
- Filtering by item aspects and other refinements using the aspect_filter parameter.
- Filtering for items that are compatible with a specific product, using the compatibility_filter parameter.
- Creating aspects histograms, which enables shoppers to drill down in each refinement narrowing the search results.
For details and examples of these capabilities, see Browse API in the Buying Integration Guide.
Pagination and sort controls
There are pagination controls (limit and offset fields) and sort query parameters that control/sort the data that is returned. By default, the results are sorted by "Best Match". For more information about Best Match, see the eBay help page Best Match.
URLs for this method
- Production URL:
https://api.ebay.com/buy/browse/v1/item_summary/search? - Sandbox URL:
https://api.sandbox.ebay.com/buy/browse/v1/item_summary/search?
Request headers
This method uses the X-EBAY-C-ENDUSERCTX request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, Request headers in the Buying Integration Guide. Restrictions
This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see API Restrictions.
eBay Partner Network: In order to receive a commission for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
+ /** @description This method searches for eBay items by various query parameters and retrieves summaries of the items. You can search by keyword, category, eBay product ID (ePID), or GTIN, charity ID, or a combination of these.
Note: Only listings where FIXED_PRICE (Buy It Now) is a buying option are returned by default. To retrieve listings that do not have FIXED_PRICE as a buying option, the buyingOptions filter can be used to retrieve those listings.
Note that an auction listing enabled with the Buy it Now feature will initially show AUCTION and FIXED_PRICE as buying options, but if/when that auction listing receives a qualifying bid, only AUCTION remains as a buying option. If this happens, the buyingOptions filter would need to be used to retrieve that auction listing.
This method also supports the following:- Filtering by the value of one or multiple fields, such as listing format, item condition, price range, location, and more. For the fields supported by this method, refer to the filter parameter.
- Retrieving the refinements (metadata) of an item, such as item aspects (color, brand) condition, category, etc. using the fieldgroups parameter.
- Filtering by item aspects and other refinements using the aspect_filter parameter.
- Filtering for items that are compatible with a specific product, using the compatibility_filter parameter.
- Creating aspects histograms, which enables shoppers to drill down in each refinement narrowing the search results.
For additional information and examples of these capabilities, refer to Browse API in the Buying Integration Guide.Pagination and sort controls
There are pagination controls (limit and offset fields) and sort query parameters that control/sort the data that are returned. By default, results are sorted by Best Match. For more information about Best Match, refer to Best Match.Restrictions
This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, refer to API Restrictions.
eBay Partner Network: In order to receive a commission for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
get: operations["search"];
put?: never;
post?: never;
@@ -30,7 +30,7 @@ export interface paths {
};
get?: never;
put?: never;
- /** @description 
This is an Experimental method. This method searches for eBay items based on a image and retrieves summaries of the items. You pass in a Base64 image in the request payload and can refine the search by category, or eBay product ID (ePID), or a combination of these using URI parameters.
To get the Base64 image string, you can use sites such as https://codebeautify.org/image-to-base64-converter.
This method also supports the following:
- Filtering by the value of one or multiple fields, such as listing format, item condition, price range, location, and more. For the fields supported by this method, see the filter parameter.
- Filtering by item aspects using the aspect_filter parameter.
For details and examples of these capabilities, see Browse API in the Buying Integration Guide.
Pagination and sort controls
There are pagination controls (limit and offset fields) and sort query parameters that control/sort the data that is returned. By default, the results are sorted by "Best Match". For more information about Best Match, see the eBay help page Best Match.
URLs for this method
- Production URL:
https://api.ebay.com/buy/browse/v1/item_summary/search_by_image? - Sandbox URL: Due to the data available, this method is not supported in the eBay Sandbox. To test your integration, use the Production URL.
Request headers
This method uses the X-EBAY-C-ENDUSERCTX request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, Request headers in the Buying Integration Guide. URL Encoding for Parameters
Query parameter values need to be URL encoded. For details, see URL encoding query parameter values. For readability, code examples in this document have not been URL encoded.
Restrictions
This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see API Restrictions.
eBay Partner Network: In order to receive a commission for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
+ /** @description This method searches for eBay items based on a image and retrieves summaries of the items. You pass in a Base64 image in the request payload and can refine the search by category, or with other available filters.
To get the Base64 image string, you can use sites such as https://codebeautify.org/image-to-base64-converter.
This method also supports the following: - Filtering by the value of one or multiple fields, such as listing format, item condition, price range, location, and more. For the fields supported by this method, refer to the filter parameter.
- Filtering by item aspects using the aspect_filter parameter.
For details and examples of these capabilities, refer to Browse API in the Buying Integration Guide.URL Encoding for Parameters
Query parameter values need to be URL encoded. For details, refer to URL encoding query parameter values. For readability, code examples in this document have not been URL encoded.Restrictions
This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, refer to API Restrictions.
eBay Partner Network: In order to receive a commission for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
post: operations["searchByImage"];
delete?: never;
options?: never;
@@ -45,7 +45,7 @@ export interface paths {
path?: never;
cookie?: never;
};
- /** @description This method retrieves the details of a specific item, such as description, price, category, all item aspects, condition, return policies, seller feedback and score, shipping options, shipping costs, estimated delivery, and other information the buyer needs to make a purchasing decision.
The Buy APIs are designed to let you create an eBay shopping experience in your app or website. This means you will need to know when something, such as the availability, quantity, etc., has changed in any eBay item you are offering. You can do this easily by setting the fieldgroups URI parameter. This parameter lets you control what is returned in the response.
Setting fieldgroups to COMPACT reduces the response to only the five fields that you need in order to check if any item detail has changed. Setting fieldgroups to PRODUCT, adds additional fields to the default response that return information about the product of the item. You can use either COMPACT or PRODUCT but not both. For more information, see fieldgroups.
URLs for this method
- Production URL:
https://api.ebay.com/buy/browse/v1/item/{item_id} - Sandbox URL:
https://api.sandbox.ebay.com/buy/browse/v1/item/{item_id}
Request headers
This method uses the X-EBAY-C-ENDUSERCTX request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, Request headers in the Buying Integration Guide. Restrictions
For a list of supported sites and other restrictions, see API Restrictions.
eBay Partner Network: In order to be commissioned for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
+ /** @description This method retrieves the details of a specific item, such as description, price, category, all item aspects, condition, return policies, seller feedback and score, shipping options, shipping costs, estimated delivery, and other information the buyer needs to make a purchasing decision.
The Buy APIs are designed to let you create an eBay shopping experience in your app or website. This means you will need to know when something, such as the availability, quantity, etc., has changed in any eBay item you are offering. This is easily achieved by setting the fieldgroups URI parameter to one of the following values:COMPACT
Reduces the response to only those fields necessary in order to determine if any item detail has changed. This field group must be used alone.PRODUCT
Adds fields to the default response that return information about the product/item. This field group may also be used in conjunction with ADDITIONAL_SELLER_DETAILS.ADDITIONAL_SELLER_DETAILS
Adds an additional field to the response that returns the seller's user ID. This field group may also be used in conjunction with PRODUCT.CHARITY_DETAILS
Adds additional fields to the response that return charity information associated with the item, if applicable.
For additional information, refer to fieldgroups.Restrictions
For a list of supported sites and other restrictions, refer to API Restrictions.
eBay Partner Network: In order to be commissioned for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
get: operations["getItem"];
put?: never;
post?: never;
@@ -62,7 +62,7 @@ export interface paths {
path?: never;
cookie?: never;
};
- /** @description This method is a bridge between the eBay legacy APIs, such as Shopping, and Finding and the eBay Buy APIs. There are differences between how legacy APIs and RESTful APIs return the identifier of an "item" and what the item ID represents. This method lets you use the legacy item ids retrieve the details of a specific item, such as description, price, and other information the buyer needs to make a purchasing decision. It also returns the RESTful item ID, which you can use with all the Buy API methods.
For more information about how to use legacy ids with the Buy APIs, see Legacy API compatibility in the Buying Integration guide.
This method returns the item details and requires you to pass in either the item ID of a non-variation item or the item ids of both the parent and child of an item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.
When an item group is created, one of the item variations, such as the red shirt size L, is chosen as the "parent". All the other items in the group are the children, such as the blue shirt size L, red shirt size M, etc.
The fieldgroups URI parameter lets you control what is returned in the response. Setting fieldgroups to PRODUCT, adds additional fields to the default response that return information about the product of the item. For more information, see fieldgroups.
URLs for this method
- Production URL:
https://api.ebay.com/buy/browse/v1/item/get_item_by_legacy_id? - Sandbox URL:
https://api.sandbox.ebay.com/buy/browse/v1/item/get_item_by_legacy_id?
Request headers
This method uses the X-EBAY-C-ENDUSERCTX request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, Request headers in the Buying Integration Guide. Restrictions
For a list of supported sites and other restrictions, see API Restrictions.
eBay Partner Network: In order to be commissioned for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
+ /** @description This method is a bridge between the eBay legacy APIs, such as Shopping and Finding, and the eBay Buy APIs. There are differences between how legacy APIs and RESTful APIs return the identifier of an "item" and what the item ID represents. This method lets you use the legacy item ids retrieve the details of a specific item, such as description, price, and other information the buyer needs to make a purchasing decision. It also returns the RESTful item_id, which you can use with all the Buy API methods.
For additional information about how to use legacy ids with the Buy APIs, refer to Item ID legacy API compatibility overview in the Buying Integration guide.
This method returns the item details and requires you to pass in either the item_id of a non-variation item or the item_id values for both the parent and child of an item group.
Note: An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.When an item group is created, one of the item variations, such as the red shirt size L, is chosen as the "parent". All other items in the group are the children, such as the blue shirt size L, red shirt size M, etc.
The fieldgroups URI parameter lets you control what is returned in the response:- Setting fieldgroups to
PRODUCT adds additional fields to the default response that return information about the product of the item. - Setting the fieldgroups to
ADDITIONAL_SELLER_DETAILS adds an additional field to the response that returns the seller's user ID. - Setting the fieldgroups to
CHARITY_DETAILS adds additional fields to the response that return charity information associated with the item, if applicable.
These fieldgroups can be used independently or at the same time. For additional information, refer to fieldgroups.Restrictions
For a list of supported sites and other restrictions, refer to API Restrictions.
eBay Partner Network: In order to be commissioned for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
get: operations["getItemByLegacyId"];
put?: never;
post?: never;
@@ -79,7 +79,7 @@ export interface paths {
path?: never;
cookie?: never;
};
- /** @description This method retrieves the details of specific items that the buyer needs to make a purchasing decision.
Note: This is a 
(Limited Release) available only to select Partners.
For this method, only the following fields are returned: eligibleForInlineCheckout, estimatedAvailabilities, itemAffiliateWebUrl, itemId, itemWebUrl, legacyItemId, price, sellerItemRevision, taxes, and topRatedBuyingExperience. URLs for this method
- Production URL:
https://api.ebay.com/buy/browse/v1/item? - Sandbox URL:
https://api.sandbox.ebay.com/buy/browse/v1/item?
Request headers
This method uses the X-EBAY-C-ENDUSERCTX request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, Request headers in the Buying Integration Guide. Restrictions
For a list of supported sites and other restrictions, see API Restrictions.
eBay Partner Network: In order to be commissioned for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
+ /** @description This method retrieves the details about specific items that buyers need to make a purchasing decision.
Note: This is a (Limited Release) available only to select Partners.
For this method, only the following fields are returned: bidCount, currentBidPrice, eligibleForInlineCheckout, enabledForGuestCheckout, estimatedAvailabilities, gtin, immediatePay, itemAffiliateWebUrl, itemCreationDate, itemEndDate, itemId, itemWebUrl, legacyItemId, minimumPriceToBid, price, priorityListing, reservePriceMet, sellerItemRevision, taxes, topRatedBuyingExperience, and uniqueBidderCount.
The array shippingOptions, which comprises multiple fields, is also returned if the X-EBAY-C-ENDUSERCTX header is supplied.Restrictions
For a list of supported sites and other restrictions, refer to API Restrictions.
eBay Partner Network: In order to be commissioned for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
get: operations["getItems"];
put?: never;
post?: never;
@@ -96,7 +96,7 @@ export interface paths {
path?: never;
cookie?: never;
};
- /** @description This method retrieves the details of the individual items in an item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.
You pass in the item group ID as a URI parameter. You use this method to show the item details of items with multiple aspects, such as color, size, storage capacity, etc.
This method returns two main containers; items and commonDescriptions. The items container has an array of containers with the details of each item in the group. The commonDescriptions container has an array of containers for a description and the item ids of all the items that have this exact description. Because items within an item group often have the same description, this decreases the size of the response.
URLs for this method
- Production URL:
https://api.ebay.com/buy/browse/v1/item/get_items_by_item_group? - Sandbox URL:
https://api.sandbox.ebay.com/buy/browse/v1/item/get_items_by_item_group?
Request headers
This method uses the X-EBAY-C-ENDUSERCTX request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, Request headers in the Buying Integration Guide. Restrictions
For a list of supported sites and other restrictions, see API Restrictions.
eBay Partner Network: In order to be commissioned for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
+ /** @description This method retrieves details about individual items in an item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.
You pass in the item_group_id as a URI parameter.
This method returns two main containers:- items
This container has an array of containers with the details about each item in the group. - commonDescriptions
This container has an array of containers for a description and the item_ids for all items that have this exact description. Because items within an item group often have the same description, this decreases the size of the response.
Setting the fieldgroup to ADDITIONAL_SELLER_DETAILS adds an additional field to the response that returns the seller's user ID. Setting the fieldgroup to CHARITY_DETAILS adds additional fields to the response that returns charity information associated with the item, if applicable. For more information, refer to fieldgroups.Restrictions
For a list of supported sites and other restrictions, refer to API Restrictions.
eBay Partner Network: In order to be commissioned for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site. */
get: operations["getItemsByItemGroup"];
put?: never;
post?: never;
@@ -115,7 +115,7 @@ export interface paths {
};
get?: never;
put?: never;
- /** @description This method checks if a product is compatible with the specified item. You can use this method to check the compatibility of cars, trucks, and motorcycles with a specific part listed on eBay.
For example, to check the compatibility of a part, you pass in the item ID of the part as a URI parameter and specify all the attributes used to define a specific car in the compatibilityProperties container. If the call is successful, the response will be COMPATIBLE, NOT_COMPATIBLE, or UNDETERMINED. See compatibilityStatus for details.
Note: The only products supported are cars, trucks, and motorcycles. To find the attributes and values for a specific marketplace, you can use the compatibility methods in the Taxonomy API. You can use this data to create menus to help buyers specify the product, such as their car.
For more details and a list of the required attributes for the US marketplace that describe motor vehicles, see Check compatibility in the Buy Integration Guide.
For an example, see the Samples section.
URLs for this method
Production URL: https://api.ebay.com/buy/browse/v1/item/{item_id}/check_compatibility
Note: This method is supported only on Production.
Restrictions
For a list of supported sites and other restrictions, see API Restrictions.
*/
+ /** @description This method checks if a product is compatible with the specified item. You can use this method to check the compatibility of cars, trucks, and motorcycles with a specific part listed on eBay.
For example, to check the compatibility of a part, you pass in the item_id of the part as a URI parameter and specify all the attributes used to define a specific car within the compatibilityProperties container. If the call is successful, the response will be COMPATIBLE, NOT_COMPATIBLE, or UNDETERMINED. Refer to compatibilityStatus for details.
Note: The only products supported are cars, trucks, and motorcycles.
To find the attributes and values for a specific marketplace, you can use the compatibility methods in the Taxonomy API. You can use this data to create menus to help buyers specify the product, such as their car.
For more information and a list of required attributes for the US marketplace that describe motor vehicles, refer to Check compatibility in the Buying Integration Guide.
For an example, refer to the Samples section.
Note: This method is supported in Sandbox but only when passing in the specified item_id and compatibility name-value pairs listed in Sample 2: Sandbox Sample.Restrictions
For a list of supported sites and other restrictions, refer to API Restrictions. */
post: operations["checkCompatibility"];
delete?: never;
options?: never;
@@ -123,112 +123,45 @@ export interface paths {
patch?: never;
trace?: never;
};
- "/shopping_cart/add_item": {
- parameters: {
- query?: never;
- header?: never;
- path?: never;
- cookie?: never;
- };
- get?: never;
- put?: never;
- /** @description Note: This is an Experimental method that is available as a (Limited Release) to select developers approved by business units. This method creates an eBay cart for the eBay member, if one does not exist, and adds items to that cart. Because a cart never expires, any item added to the cart will remain in the cart until it is removed.
To use this method, you must submit a RESTful item ID and the quantity of the item. If the quantity value is greater than the number of available, the quantity value is changed to the number available and a warning is returned. For example, if there are 15 baseballs available and you set the quantity value to 50, the service automatically changes the value of quantity to 15.
The response returns all the items in the eBay member's cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. The quantity and state of an item changes often. If the item becomes "unavailable" such as, when the listing has ended or the item is out of stock, whether it has just been added to the cart or has been in the cart for some time, the item will be returned in the unavailableCartItems container.
Note: There are differences between how legacy APIs, such as Finding, and RESTful APIs, such as Browse, return the identifier of an "item" and what the item ID represents. If you have an item ID from one of the legacy APIs, you can use the legacy item ID with the getItemByLegacyId method to retrieve the RESTful ID for that item. For more information about how to use legacy IDs with the Buy APIs, see Legacy API compatibility in the Buying Integration guide.
URLs for this method
- Production URL:
https://api.ebay.com/buy/browse/v1/shopping_cart/add_item - Sandbox URL:
https://api.sandbox.ebay.com/buy/browse/v1/shopping_cart/add_item
Note: This method is not available in the eBay API Explorer.
Restrictions
- This method can be used only for eBay members.
- You can add only items with a FIXED_PRICE that accept PayPal as a payment.
For a list of supported sites and other restrictions, see API Restrictions.
*/
- post: operations["addItem"];
- delete?: never;
- options?: never;
- head?: never;
- patch?: never;
- trace?: never;
- };
- "/shopping_cart/": {
- parameters: {
- query?: never;
- header?: never;
- path?: never;
- cookie?: never;
- };
- /** @description Note: This is an experimental method that is available as a (Limited Release) to select developers approved by business units. This method retrieves all the items in the eBay member's cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. There are no URI parameters or request payload.
The response returns the summary details of all the items in the eBay member's cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. If the cart is empty, the response is HTTP 204.
The quantity and state of an item changes often. If the item becomes "unavailable" such as, when the listing has ended or the item is out of stock, the item will be returned in the unavailableCartItems container. URLs for this method
- Production URL:
https://api.ebay.com/buy/browse/v1/shopping_cart/ - Sandbox URL:
https://api.sandbox.ebay.com/buy/browse/v1/shopping_cart/
Note: This method is not available in the eBay API Explorer.
Restrictions
This method can be used only for eBay members. For a list of supported sites and other restrictions, see API Restrictions.
*/
- get: operations["getShoppingCart"];
- put?: never;
- post?: never;
- delete?: never;
- options?: never;
- head?: never;
- patch?: never;
- trace?: never;
- };
- "/shopping_cart/remove_item": {
- parameters: {
- query?: never;
- header?: never;
- path?: never;
- cookie?: never;
- };
- get?: never;
- put?: never;
- /** @description Note: This is an experimental method that is available as a (Limited Release) to select developers approved by business units. This method removes a specific item from the eBay member's cart. You specify the ID of the item in the cart (cartItemId) that you want to remove.
The response returns all the items in the eBay member's cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. If you remove the last item in the cart, the response is HTTP 204.
The quantity and state of an item changes often. If the item becomes "unavailable" such as, when the listing has ended or the item is out of stock, the item will be returned in the unavailableCartItems container.
Note: The cartItemId is not the same as the item ID. The cartItemId is the identifier of a specific item in the cart and is generated when the item was added to the cart.
URLs for this method
- Production URL:
https://api.ebay.com/buy/browse/v1/shopping_cart/remove_item - Sandbox URL:
https://api.sandbox.ebay.com/buy/browse/v1/shopping_cart/remove_item
Note: This method is not available in the eBay API Explorer.
Restrictions
This method can be used only for eBay members. For a list of supported sites and other restrictions, see API Restrictions.
*/
- post: operations["removeItem"];
- delete?: never;
- options?: never;
- head?: never;
- patch?: never;
- trace?: never;
- };
- "/shopping_cart/update_quantity": {
- parameters: {
- query?: never;
- header?: never;
- path?: never;
- cookie?: never;
- };
- get?: never;
- put?: never;
- /** @description Note: This is an experimental method that is available as a (Limited Release) to select developers approved by business units. This method updates the quantity value of a specific item in the eBay member's cart. You specify the ID of the item in the cart (cartItemId) and the new value for the quantity. If the quantity value is greater than the number of available, the quantity value is changed to the number available and a warning is returned. For example, if there are 15 baseballs available and you set the quantity value to 50, the service automatically changes the value of quantity to 15.
The response returns all the items in the eBay member's cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. The quantity and state of an item changes often. If the item becomes "unavailable" such as, the listing has ended or the item is out of stock, the item will be returned in the unavailableCartItems container.
Note: The cartItemId is not the same as the item ID. The cartItemId is the identifier of a specific item in the cart and is generated when the item was added to the cart.
URLs for this method
- Production URL:
https://api.ebay.com/buy/browse/v1/shopping_cart/update_quantity - Sandbox URL:
https://api.sandbox.ebay.com/buy/browse/v1/shopping_cart/update_quantity
Note: This method is not available in the eBay API Explorer.
Restrictions
This method can be used only for eBay members. For a list of supported sites and other restrictions, see API Restrictions.
*/
- post: operations["updateQuantity"];
- delete?: never;
- options?: never;
- head?: never;
- patch?: never;
- trace?: never;
- };
}
export type webhooks = Record;
export interface components {
schemas: {
- /** @description The type that defines the fields for the addItems request. */
- AddCartItemInput: {
- /** @description The eBay RESTful identifier of the item you want added to the cart.
RESTful Item ID Format: v1|#|#
For example:
v1|2**********2|0
v1|1**********2|4**********2
For more information about item ID for RESTful APIs, see the Legacy API compatibility section of the Buy APIs Overview.
Maximum number of items in a cart: 100 */
- itemId?: string;
- /**
- * Format: int32
- * @description The number of this item the buyer wants to purchase. If this value is greater than the number available, the service will change this value to the number available. If this happens, a warning is returned.
Maximum: number available
- */
- quantity?: number;
- };
- /** @description The type that defines the array of product identifiers associated with the item. This container is returned if the seller has associated the eBay Product Identifier (ePID) with the item and in the request fieldgroups is set to PRODUCT. */
+ /** @description The type that defines the array of product identifiers associated with the item. This container is returned if the seller has associated the eBay Product Identifier (ePID) with the item, and in the request fieldgroups is set to PRODUCT. */
AdditionalProductIdentity: {
- /** @description An array of the product identifier/value pairs for the product associated with the item. This is returned if the seller has associated the eBay Product Identifier (ePID) with the item and the request has fieldgroups set to PRODUCT.
The following table shows what is returned, based on the item information provided by the seller, when the fieldgroups set to PRODUCT.
| ePID Provided | Product ID(s) Provided | Response |
| No | No | The AdditionalProductIdentity container is not returned. |
| No | Yes | The AdditionalProductIdentity container is not returned but the product identifiers specified by the seller are returned in the localizedAspects container. |
| Yes | No | The AdditionalProductIdentity container is returned listing the product identifiers of the product. |
| Yes | Yes | The AdditionalProductIdentity container is returned listing all the product identifiers of the product and the product identifiers specified by the seller are returned in the localizedAspects container. |
*/
+ /** @description An array of product identifier/value pairs for the product associated with the item. This is returned if the seller has associated the eBay Product Identifier (ePID) with the item and the request has fieldgroups set to PRODUCT.
The following table shows what is returned, based on the item information provided by the seller, when fieldgroups is set to PRODUCT.
| ePID Provided | Product ID(s) Provided | Response |
|---|
| No | No | The AdditionalProductIdentity container is not returned. |
| No | Yes | The AdditionalProductIdentity container is not returned but the product identifiers specified by the seller are returned in the localizedAspects container. |
| Yes | No | The AdditionalProductIdentity container is returned listing the product identifiers of the product. |
| Yes | Yes | The AdditionalProductIdentity container is returned listing all the product identifiers of the product and the product identifiers specified by the seller are returned in the localizedAspects container. |
AUTHENTICITY_GUARANTEE. For implementation help, refer to eBay API documentation */
+ serviceType?: string;
+ };
/** @description The type that defines the fields for an address. */
Address: {
- /** @description The first line of the street address. Note: This is conditionally returned in the itemLocation field. */
+ /** @description The first line of the street address.
Note: This is conditionally returned in the itemLocation field. */
addressLine1?: string;
- /** @description The second line of the street address. This field is not always used, but can be used for 'Suite Number' or 'Apt Number'. */
+ /** @description The second line of the street address. This field is not always used, but can be used for "Suite Number" or "Apt Number". */
addressLine2?: string;
/** @description The city of the address. */
city?: string;
- /** @description The two-letter ISO 3166 standard of the country of the address. For implementation help, refer to eBay API documentation */
+ /** @description The two-letter ISO 3166 standard code for the country of the address. For implementation help, refer to eBay API documentation */
country?: string;
/** @description The county of the address. */
county?: string;
- /** @description The postal code (or zip code in US) code of the address. Sellers set a postal code (or zip code in US) for items when they are listed. The postal code is used for calculating proximity searches. It is anonymized when returned in itemLocation.postalCode via the API. */
+ /** @description The postal code (or zip code in US) code of the address. Sellers set a postal code (or zip code in US) for items when they are listed. The postal code is used for calculating proximity searches. It is anonymized when returned in itemLocation.postalCode via the API. */
postalCode?: string;
- /** @description The state or province of the address. Note: This is conditionally returned in the itemLocation field. */
+ /** @description The state or province of the address.
Note: This is conditionally returned in the itemLocation field. */
stateOrProvince?: string;
};
Amount: {
- /** @description The list of valid currencies. Each ISO 4217 currency code includes the currency name followed by the numeric value.
For example, the Canadian Dollar code (CAD) would take the following form: Canadian Dollar, 124. For implementation help, refer to eBay API documentation */
+ /** @description The list of valid currencies. Each ISO 4217 currency code includes the currency name followed by the numeric value.
For example, the Canadian Dollar code (CAD) would take the following form: Canadian Dollar, 124. For implementation help, refer to eBay API documentation */
currency?: string;
/** @description The value of the discounted amount. */
value?: string;
@@ -242,18 +175,18 @@ export interface components {
};
/** @description The type that define the fields for the aspect information. Aspects are the variations of an item, such as color, size, etc. */
AspectDistribution: {
- /** @description An array of containers for the various values of the aspect and the match count and a HATEOAS reference ( refinementHref) for this aspect. */
+ /** @description An array of containers for the various values of the aspect and the match count, and a HATEOAS reference (refinementHref) for this aspect. */
aspectValueDistributions?: components["schemas"]["AspectValueDistribution"][];
- /** @description The name of an aspect, such as Brand, Color, etc. */
+ /** @description The name of an aspect, such as Brand, Color, etc. */
localizedAspectName?: string;
};
AspectGroup: {
/** @description An array of the name/value pairs for the aspects of the product. For example: BRAND/Apple */
aspects?: components["schemas"]["Aspect"][];
- /** @description The name of a group of aspects.
In the following example, Product Identifiers and Process are product aspect group names. Under the group name are the product aspect name/value pairs. Product Identifiers
Brand/Apple
Product Family/iMac
Processor
Processor Type/Intel
Processor Speed/3.10
*/
+ /** @description The name of a group of aspects.
In the following example, Product Identifiers and Process are product aspect group names. Under the group name are the product aspect name/value pairs.
Product Identifiers
Brand/Apple
Product Family/iMac
Processor
Processor Type/Intel
Processor Speed/3.10 */
localizedGroupName?: string;
};
- /** @description The container that defines the fields for the conditions refinements. This container is returned when fieldgroups is set to ASPECT_REFINEMENTS or FULL in the request. */
+ /** @description The container that defines the fields for the conditions refinements. This container is returned when fieldgroups is set to ASPECT_REFINEMENTS or FULL in the request. */
AspectValueDistribution: {
/** @description The value of an aspect. For example, Red is a value for the aspect Color. */
localizedAspectValue?: string;
@@ -265,11 +198,11 @@ export interface components {
/** @description A HATEOAS reference for this aspect. */
refinementHref?: string;
};
- /** @description The type the defines attribute name/value pair fields that specify a product. The type of data depends on the context. For example, if you were using this to specify a specific vehicle, the attribute names would be Make, Model, Year, etc. */
+ /** @description The type the defines attribute name/value pair fields that specify a product. The type of data depends on the context. For example, if you were using this to specify a specific vehicle, the attribute names would be Make, Model, Year, etc. */
AttributeNameValue: {
- /** @description The name of the product attribute, such as Make, Model, Year, etc. */
+ /** @description The name of the product attribute, such as Make, Model, Year, etc. */
name?: string;
- /** @description The value for the name attribute, such as BMW, R1200GS, 2011, etc. */
+ /** @description The value for the name attribute, such as BMW, R1200GS, 2011, etc. */
value?: string;
};
/** @description A type that identifies whether the item is qualified for the Authenticity Guarantee program. */
@@ -297,16 +230,16 @@ export interface components {
discountAmount?: components["schemas"]["Amount"];
/** @description The type of discount that the coupon applies. For implementation help, refer to eBay API documentation */
discountType?: string;
- /** @description A description of the coupon.
Note: The value returned in the termsWebUrl field should appear for all experiences when displaying coupons. The value in the availableCoupons.message field must also be included, if returned in the API response. */
+ /** @description A description of the coupon.
Note: The value returned in the termsWebUrl field should appear for all experiences when displaying coupons. The value in the availableCoupons.message field must also be included if returned in the API response. */
message?: string;
/** @description The coupon code. */
redemptionCode?: string;
- /** @description The URL to the coupon terms of use.
Note: The value returned in the termsWebUrl field should appear for all experiences when displaying coupons. The value in the availableCoupons.message field must also be included, if returned in the API response. */
+ /** @description The URL to the coupon terms of use.
Note: The value returned in the termsWebUrl field should appear for all experiences when displaying coupons. The value in the availableCoupons.message field must also be included if returned in the API response. */
termsWebUrl?: string;
};
- /** @description The container that defines the fields for the buying options refinements. This container is returned when fieldgroups is set to BUYING_OPTION_REFINEMENTS or FULL in the request. */
+ /** @description The container that defines the fields for the buying options refinements. This container is returned when fieldgroups is set to BUYING_OPTION_REFINEMENTS or FULL in the request. */
BuyingOptionDistribution: {
- /** @description The container that returns the buying option type. This will be AUCTION or FIXED_PRICE or both. For details, see buyingOptions. */
+ /** @description The container that returns the buying option type. This will be AUCTION, FIXED_PRICE, CLASSIFIED_AD, or a combination of these options. For details, see buyingOptions. */
buyingOption?: string;
/**
* Format: int32
@@ -316,38 +249,18 @@ export interface components {
/** @description The HATEOAS reference for this buying option. */
refinementHref?: string;
};
- /** @description The type that defines the fields for the individual items in a cart. */
- CartItem: {
- /** @description The identifier for the item being added to the cart. This is generated when the item is added to the cart. */
- cartItemId?: string;
- /** @description This is the subtotal of cost of a specific item in the cart. This does not include taxes, shipping costs, discounts, etc. It is price * quantity. */
- cartItemSubtotal?: components["schemas"]["Amount"];
- /** @description The primary image of the item. This is the image that appears on the eBay view item page for this item. */
- image?: components["schemas"]["Image"];
- /** @description The RESTful identifier of the item. This identifier is generated when the item was listed.
RESTful Item ID Format: v1|#|#
For example:
v1|2**********2|0
v1|1**********2|4**********2 */
- itemId?: string;
- /** @description The URL of the eBay view item page for the item. */
- itemWebUrl?: string;
- /** @description The cost of the item. */
- price?: components["schemas"]["Price"];
- /**
- * Format: int32
- * @description The number of this item the buyer wants to purchase.
- */
- quantity?: number;
- /** @description The title of the item. This can be written by the seller or come from the eBay product catalog. */
- title?: string;
- };
- /** @description This type is used by the categories container in the response of the search method, and contains the primary item category ID of the item, as well as the secondary item category if the item was listed in two categories. */
+ /** @description This type is used by the categories container in the response of the search method, and contains the name and ID of the item category. */
Category: {
- /** @description The unique identifier of the primary item category of the item, as well as the secondary item category if item was listed in two categories. */
+ /** @description The unique identifier of the category. */
categoryId?: string;
+ /** @description The name of the category. */
+ categoryName?: string;
};
- /** @description The container that defines the fields for the category refinements. This container is returned when fieldgroups is set to CATEGORY_REFINEMENTS or FULL in the request. */
+ /** @description The container that defines the fields for the category refinements. This container is returned when fieldgroups is set to CATEGORY_REFINEMENTS or FULL in the request. */
CategoryDistribution: {
- /** @description The identifier of the category. */
+ /** @description The unique identifier of the category. */
categoryId?: string;
- /** @description The name of the category, such as Baby & Toddler Clothing. */
+ /** @description The name of the category, such as Baby & Toddler Clothing. */
categoryName?: string;
/**
* Format: int32
@@ -357,39 +270,80 @@ export interface components {
/** @description The HATEOAS reference of this category. */
refinementHref?: string;
};
- /** @description The type that defines the fields for the item ids that all use a common description. Often the item variations within an item group all have the same description. Instead of repeating this description in the item details of each item, a description that is shared by at least one other item is returned in this container. If the description is unique, it is returned in the items.description field. */
+ /** @description The type that defines the fields for the item_id values that all use a common description. Often the item variations within an item group all have the same description. Instead of repeating this description in the item details of each item, a description that is shared by at least one other item is returned in this container. If the description is unique, it is returned in the items.description field. */
CommonDescriptions: {
/** @description The item description that is used by more than one of the item variations. */
description?: string;
/** @description A list of item ids that have this description. */
itemIds?: string[];
};
- /** @description An array of attribute name/value pairs used to define a specific product. For example: If you wanted to specify a specific car, one of the name/value pairs would be
"name" : "Year",
"value" : "2019" For a list of the attributes required for cars and trucks and motorcycles see Check compatibility in the Buy Integration Guide.
*/
+ /** @description This type is used to provide contact information for the manufacturer of the product. */
+ CompanyAddress: {
+ /** @description The first line of the product manufacturer's street address. */
+ addressLine1?: string;
+ /** @description The second line of the product manufacturer's street address. This field is not always used, but can be used for secondary address information such as 'Suite Number' or 'Apt Number'. */
+ addressLine2?: string;
+ /** @description The city of the product manufacturer's street address. */
+ city?: string;
+ /** @description The company name of the product manufacturer. */
+ companyName?: string;
+ /** @description The contact URL of the product manufacturer. */
+ contactUrl?: string;
+ /** @description The two-letter ISO 3166 standard code for the country of the address. For implementation help, refer to eBay API documentation */
+ country?: string;
+ /** @description The country name of the product manufacturer's street address. */
+ countryName?: string;
+ /** @description The county of the product manufacturer's street address. */
+ county?: string;
+ /** @description The product manufacturer's business email address. */
+ email?: string;
+ /** @description The product manufacturer's business phone number. */
+ phone?: string;
+ /** @description The postal code of the product manufacturer's street address. */
+ postalCode?: string;
+ /** @description The state or province of the product manufacturer's street address. */
+ stateOrProvince?: string;
+ };
+ /** @description An array of attribute name/value pairs used to define a specific product. For example: If you wanted to specify a specific car, one of the name/value pairs would be:
"name" : "Year",
"value" : "2019"
For a list of the attributes required for cars and trucks and motorcycles refer to Check compatibility in the Buying Integration Guide. */
CompatibilityPayload: {
- /** @description An array of attribute name/value pairs used to define a specific product. For example: If you wanted to specify a specific car, one of the name/value pairs would be
"name" : "Year",
"value" : "2019" For a list of the attributes required for cars and trucks and motorcycles see Check compatibility in the Buy Integration Guide.
*/
+ /** @description An array of attribute name/value pairs used to define a specific product. For example: If you wanted to specify a specific car, one of the name/value pairs would be
"name" : "Year",
"value" : "2019"
For a list of the attributes required for cars and trucks and motorcycles see Check compatibility in the Buy Integration Guide. */
compatibilityProperties?: components["schemas"]["AttributeNameValue"][];
};
- /** @description This container returns the product attribute name/value pairs that are compatible with the keyword. These attributes are submitted in the compatibility_filter request field. */
+ /** @description This container returns the product attribute name/value pairs that are compatible with the keyword. These attributes are submitted in the compatibility_filter request field. */
CompatibilityProperty: {
/** @description The name of the product attribute that as been translated to the language of the site. */
localizedName?: string;
/** @description The name of the product attribute, such as Make, Model, Year, etc. */
name?: string;
- /** @description The value for the name attribute, such as BMW, R1200GS, 2011, etc. */
+ /** @description The value for the name attribute, such as BMW, R1200GS, 2011, etc. */
value?: string;
};
/** @description The type that defines the response fields for checkCompatibility. */
CompatibilityResponse: {
- /** @description An enumeration value that tells you if the item is compatible with the product.
The values are: - COMPATIBLE - Indicates the item is compatible with the product specified in the request.
- NOT_COMPATIBLE - Indicates the item is not compatible with the product specified in the request. Be sure to check all the value fields to ensure they are correct as errors in the value can also cause this response.
- UNDETERMINED - Indicates one or more attributes for the specified product are missing so compatibility cannot be determined. The response returns the attributes that are missing.
Code so that your app gracefully handles any future changes to this list. For implementation help, refer to eBay API documentation */
+ /** @description An enumeration value that tells you if the item is compatible with the product.
The values are: - COMPATIBLE - Indicates the item is compatible with the product specified in the request.
- NOT_COMPATIBLE - Indicates the item is not compatible with the product specified in the request. Be sure to check all the value fields to ensure they are correct as errors in the value can also cause this response.
- UNDETERMINED - Indicates one or more attributes for the specified product are missing so compatibility cannot be determined. The response returns the attributes that are missing.
Code so that your app gracefully handles any future changes to this list. For implementation help, refer to eBay API documentation */
compatibilityStatus?: string;
/** @description An array of warning messages. These types of errors do not prevent the method from executing but should be checked. */
warnings?: components["schemas"]["Error"][];
};
- /** @description The container that defines the fields for the conditions refinements. This container is returned when fieldgroups is set to CONDITION_REFINEMENTS or FULL in the request. */
+ /** @description This type displays additional information about the condition of an item in a structured format. */
+ ConditionDescriptor: {
+ /** @description The name of a condition descriptor. The value(s) for this condition descriptor is returned in the associated values array. */
+ name?: string;
+ /** @description This array displays the value(s) for a condition descriptor (denoted by the associated name field), as well as any other additional information about the condition of the item. */
+ values?: components["schemas"]["ConditionDescriptorValue"][];
+ };
+ /** @description This type displays the value(s) associated with the specified condition descriptor name, as well as any additional information about a condition descriptor. */
+ ConditionDescriptorValue: {
+ /** @description Additional information about the condition of an item as it relates to a condition descriptor. This array elaborates on the value specified in the content field and provides additional details about the condition of an item. */
+ additionalInfo?: string[];
+ /** @description The value for the condition descriptor indicated in the associated name field. */
+ content?: string;
+ };
+ /** @description The container that defines the fields for the conditions refinements. This container is returned when fieldgroups is set to CONDITION_REFINEMENTS or FULL in the request. */
ConditionDistribution: {
- /** @description The text describing the condition of the item, such as New or Used. For a list of condition names, see Item Condition IDs and Names.
Code so that your app gracefully handles any future changes to this list.
Note: As of September 1, 2021, condition ID 2500 ('Seller Refurbished') is no longer a valid item condition in the Cell Phones & Smartphones category (category ID 9355) for the following marketplaces: US, Canada, UK, Germany, and Australia. This refurbished item condition has been replaced by three new refurbished values, which include 'Excellent - Refurbished' (condition ID 2010), 'Very Good - Refurbished' (condition ID 2020), and 'Good - Refurbished' (condition ID 2030). */
+ /** @description The text describing the condition of the item, such as New or Used. For a list of condition names, refer to Item Condition IDs and Names. */
condition?: string;
- /** @description The identifier of the condition. For example, 1000 is the identifier for NEW.
Note: As of September 1, 2021, condition ID 2500 ('Seller Refurbished') is no longer a valid item condition in the Cell Phones & Smartphones category (category ID 9355) for the following marketplaces: US, Canada, UK, Germany, and Australia. This refurbished item condition has been replaced by three new refurbished values, which include 'Excellent - Refurbished' (condition ID 2010), 'Very Good - Refurbished' (condition ID 2020), and 'Good - Refurbished' (condition ID 2030). */
+ /** @description The identifier of the condition. For example, 1000 is the identifier for NEW. */
conditionId?: string;
/**
* Format: int32
@@ -401,24 +355,24 @@ export interface components {
};
/** @description This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable. */
ConvertedAmount: {
- /** @description The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency. For implementation help, refer to eBay API documentation */
+ /** @description The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency. For implementation help, refer to eBay API documentation */
convertedFromCurrency?: string;
- /** @description The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field. */
+ /** @description The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field. */
convertedFromValue?: string;
- /** @description The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.
Default: The currency of the authenticated user's country. For implementation help, refer to eBay API documentation */
+ /** @description The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.
Default: The currency of the authenticated user's country. For implementation help, refer to eBay API documentation */
currency?: string;
- /** @description The monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency. */
+ /** @description The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency. */
value?: string;
};
/** @description An array of containers with the details for all of the items returned. */
CoreItem: {
/** @description An array of containers with the URLs for the images that are in addition to the primary image. The primary image is returned in the image.imageUrl field. */
additionalImages?: components["schemas"]["Image"][];
- /** @description This indicates if the item is for adults only. For more information about adult-only items on eBay, see Adult items policy for sellers and Adult-Only items on eBay for buyers. */
+ /** @description This indicates if the item is for adults only. For more information about adult-only items on eBay, see Adult items policy for sellers and Adult-Only items on eBay for buyers. */
adultOnly?: boolean;
/** @description (Primary Item Aspect) The age group for which the product is recommended. For example, newborn, infant, toddler, kids, adult, etc. All the item aspects, including this aspect, are returned in the localizedAspects container. */
ageGroup?: string;
- /** @description A container for information about whether an item is qualified for the Authenticity Guarantee program.
Under the Authenticity Guarantee program, the seller ships a purchased item to a a third-party authenticator who inspects the item and provides an authentication card for it before the item is shipped to the buyer. If the buyer returns the item, the authenticator first verifies that it is the same item in the same condition before returning it to the seller.
Note: Refer to the Authenticity Guarantee page for more information. */
+ /** @description A container for information about whether an item is qualified for the Authenticity Guarantee program.
Under the Authenticity Guarantee program, the seller ships a purchased item to a a third-party authenticator who inspects the item and provides an authentication card for it before the item is shipped to the buyer. If the buyer returns the item, the authenticator first verifies that it is the same item in the same condition before returning it to the seller.
Note: Refer to the Authenticity Guarantee page for more information. */
authenticityGuarantee?: components["schemas"]["AuthenticityGuaranteeProgram"];
/** @description A container for information about whether an item is from a verified seller.
![\"Experimental](\"/cms/img/docs/experimental-icon.svg\" "\\"Experimental"){kind=icon}
(Experimental) Lets shoppers search for specific items by image. You can refine the results by using URI parameters and filters.