M2M Public API Service — client.commerce.message¶
Version 1.0.0 · base path /commerce/message/v1 · async twin: the same methods on
AsyncEbayClient, awaited.
Operations¶
Bases: BaseResource
bulk_update_conversation ¶
bulk_update_conversation(*, body: BulkUpdateConversationsRequest | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[False] = False) -> commerce_message_models.BulkUpdateConversationsResponse
bulk_update_conversation(*, body: BulkUpdateConversationsRequest | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[True]) -> httpx.Response
bulk_update_conversation(*, body: BulkUpdateConversationsRequest | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: bool = False) -> commerce_message_models.BulkUpdateConversationsResponse | httpx.Response
This method can be used to update the conversationStatus of up to 10 conversations. The conversationId , existing conversationType , and updated conversationStatus for each conversation to modify are required in the conversations array. Important! Although it cannot be updated, the conversationType field is required for each conversation being updated.
get_conversation ¶
get_conversation(conversation_id: str, *, conversation_type: str, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[False] = False) -> commerce_message_models.GetMessagesByConversationIdResponse
get_conversation(conversation_id: str, *, conversation_type: str, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[True]) -> httpx.Response
get_conversation(conversation_id: str, *, conversation_type: str, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: bool = False) -> commerce_message_models.GetMessagesByConversationIdResponse | httpx.Response
This method can be used to retrieve messages within a specific conversation. The conversation_id of the conversation for which to retrieve messages is required as a path parameter and the conversation_type of the conversation is required as a query parameter.
get_conversations ¶
get_conversations(*, conversation_type: str, conversation_status: str | None = None, end_time: str | None = None, limit: int | str | None = None, offset: int | str | None = None, other_party_username: str | None = None, reference_id: str | None = None, reference_type: str | None = None, start_time: str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[False] = False) -> commerce_message_models.GetAllMyConversationsResponse
get_conversations(*, conversation_type: str, conversation_status: str | None = None, end_time: str | None = None, limit: int | str | None = None, offset: int | str | None = None, other_party_username: str | None = None, reference_id: str | None = None, reference_type: str | None = None, start_time: str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[True]) -> httpx.Response
get_conversations(*, conversation_type: str, conversation_status: str | None = None, end_time: str | None = None, limit: int | str | None = None, offset: int | str | None = None, other_party_username: str | None = None, reference_id: str | None = None, reference_type: str | None = None, start_time: str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: bool = False) -> commerce_message_models.GetAllMyConversationsResponse | httpx.Response
This method can be used to retrieve one or more conversations associated with a user. The conversation_type query parameter is required when using this method to specify if the retrieved conversations are from eBay or from members. The result set can also optionally be filtered by conversation status, reference, username, and/or time range.
send_message ¶
send_message(*, body: SendMessageRequest | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[False] = False) -> commerce_message_models.SendMessageResponse
send_message(*, body: SendMessageRequest | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[True]) -> httpx.Response
send_message(*, body: SendMessageRequest | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: bool = False) -> commerce_message_models.SendMessageResponse | httpx.Response
This method can be used to start a conversation with another user or send a message in an existing conversation with another user based on the information provided in the request. To send a message, one of the conversationId or otherPartyUsername request fields is required.
update_conversation ¶
update_conversation(*, body: UpdateConversationRequest | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[False] = False) -> None
update_conversation(*, body: UpdateConversationRequest | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[True]) -> httpx.Response
update_conversation(*, body: UpdateConversationRequest | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: bool = False) -> None | httpx.Response
This method can be used to update the conversationStatus or the read status of a specified conversation. Note: Only one of these statuses can be updated at a time using this method. If both fields are included, only the read status of the specified conversation will be updated and the conversationStatus field will be ignored.
Models¶
BulkConversation ¶
Bases: EbayModel
conversation_id
class-attribute
instance-attribute
¶
conversation_id = Field(None, alias='conversationId', description='This field indicates the unique identifier of the conversation that is to be updated. Use the getConversations method to retrieve conversation ID values.')
conversation_status
class-attribute
instance-attribute
¶
conversation_status = Field(None, alias='conversationStatus', description='This field indicates the status for which to update the associated conversation. Valid values: ACTIVE ARCHIVE DELETE READ UNREAD')
conversation_type
class-attribute
instance-attribute
¶
conversation_type = Field(None, alias='conversationType', description='This field specifies the existing type of the conversation that is to be updated. Important! This value cannot be updated using this method but is required for each conversation being updated. Valid values: FROM_MEMBERS FROM_EBAY')
BulkUpdateConversationsRequest ¶
Bases: EbayModel
conversations
class-attribute
instance-attribute
¶
conversations = Field(None, description='This array specifies the list of conversations to update and the updated conversationStatus for each.')
ConversationsMetadata ¶
Bases: EbayModel
total_conversations_count
class-attribute
instance-attribute
¶
total_conversations_count = Field(None, alias='totalConversationsCount', description='The total number of conversations being updated.')
update_failure_count
class-attribute
instance-attribute
¶
update_failure_count = Field(None, alias='updateFailureCount', description='The number of conversations in which the specified update failed.')
update_success_count
class-attribute
instance-attribute
¶
update_success_count = Field(None, alias='updateSuccessCount', description='The number of conversations in which the specified update succeeded.')
ConversationsResponse ¶
Bases: EbayModel
conversation_id
class-attribute
instance-attribute
¶
conversation_id = Field(None, alias='conversationId', description='The unique identifier of the conversation.')
update_status
class-attribute
instance-attribute
¶
update_status = Field(None, alias='updateStatus', description='The update status of the conversation, such as SUCCESS or FAILURE .')
ErrorParameter ¶
MessageMedia ¶
Bases: EbayModel
media_name
class-attribute
instance-attribute
¶
media_name = Field(None, alias='mediaName', description='The name of the media attached to the message.')
media_type
class-attribute
instance-attribute
¶
media_type = Field(None, alias='mediaType', description='The type of media attached to the message. Valid values: IMAGE PDF DOC TXT')
media_url
class-attribute
instance-attribute
¶
media_url = Field(None, alias='mediaUrl', description='The URL of the self-hosted media attached to the message. URLs must use the "HTTPS" protocol.')
Reference ¶
Bases: EbayModel
reference_id
class-attribute
instance-attribute
¶
reference_id = Field(None, alias='referenceId', description='This value indicates the reference ID associated with the corresponding referenceType value. For example, in the case of a LISTING reference type, this value will be the item ID value of the listing.')
reference_type
class-attribute
instance-attribute
¶
reference_type = Field(None, alias='referenceType', description='This value indicates the reference type to associate with the conversation. The reference type is used to specify what the conversation is in reference to. For example, a value of LISTING specifies that the conversation is associated with a specific listing. The item ID associated with this listing will then be returned in the referenceId field.')
SendMessageRequest ¶
Bases: EbayModel
conversation_id
class-attribute
instance-attribute
¶
conversation_id = Field(None, alias='conversationId', description='This field specifies the unique identifier of the conversation in which to send the message. Use the getConversations method to retrieve conversation ID values. This field is required if sending a message in an existing conversation.')
email_copy_to_sender
class-attribute
instance-attribute
¶
email_copy_to_sender = Field(None, alias='emailCopyToSender', description='This boolean indicates whether a copy of the message should be emailed to the sender. If this boolean is input as true , a copy of the message will be emailed to the sender.')
message_media
class-attribute
instance-attribute
¶
message_media = Field(None, alias='messageMedia', description='This array lists the individual forms of media, if any, to be attached to the message. Up to five individual forms of media may be sent per message. If more than five are specified in this array, an error will occur and the call will fail.')
message_text
class-attribute
instance-attribute
¶
message_text = Field(None, alias='messageText', description='The text of the message. Maximum length: 2000 characters')
other_party_username
class-attribute
instance-attribute
¶
other_party_username = Field(None, alias='otherPartyUsername', description='This field specifies the eBay username of the entity to whom to send the message. This field is required if starting a new conversation with another eBay user. 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.')
reference
class-attribute
instance-attribute
¶
reference = Field(None, description='This container should be used if the new or existing conversation is related to a specific eBay listing. For example, a referenceType of LISTING and an associated referenceId will specify the item ID value of the listing associated with the message.')
SendMessageResponse ¶
Bases: EbayModel
created_date
class-attribute
instance-attribute
¶
created_date = Field(None, alias='createdDate', description='The date the message was sent in ISO 8601 format.')
message_body
class-attribute
instance-attribute
¶
message_body = Field(None, alias='messageBody', description='The message text.')
message_id
class-attribute
instance-attribute
¶
message_id = Field(None, alias='messageId', description='The unique identifier of the message.')
message_media
class-attribute
instance-attribute
¶
message_media = Field(None, alias='messageMedia', description='This array will be returned if the user attached one or more images or documents to the message.')
read_status
class-attribute
instance-attribute
¶
read_status = Field(None, alias='readStatus', description='The read status of the message. If returned as true , the message has been read. If returned as false , the message has not been read.')
recipient_user_name
class-attribute
instance-attribute
¶
recipient_user_name = Field(None, alias='recipientUserName', description='The eBay username of the recipient. 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 .')
sender_user_name
class-attribute
instance-attribute
¶
sender_user_name = Field(None, alias='senderUserName', description='The eBay username of the sender. 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 .')
subject
class-attribute
instance-attribute
¶
subject = Field(None, description='The subject line of the message.')
UpdateConversationRequest ¶
Bases: EbayModel
conversation_id
class-attribute
instance-attribute
¶
conversation_id = Field(None, alias='conversationId', description='This field specifies the unique identifier of the conversation that is to be updated. Use the getConversations method to retrieve conversation ID values.')
conversation_status
class-attribute
instance-attribute
¶
conversation_status = Field(None, alias='conversationStatus', description='This field specifies the status for which to update the specified conversation. Valid values: ACTIVE ARCHIVE DELETE Note: This field should not be used in conjunction with the read field. If both fields are input in the request, only the read status will be updated for the specified conversation and the conversationStatus field will be ignored.')
conversation_type
class-attribute
instance-attribute
¶
conversation_type = Field(None, alias='conversationType', description='This field specifies the existing type of the conversation being updated. Important! This value cannot be updated using this method but is required as part of the request payload. Valid values: FROM_MEMBERS FROM_EBAY')
read
class-attribute
instance-attribute
¶
read = Field(None, description="This boolean specifies the read status for which to update the conversation. If set to true , the conversation will update to 'read', and if set to false , the conversation will update to 'unread'. Note: This field should not be used in conjunction with the conversationStatus field.")
BulkUpdateConversationsResponse ¶
Bases: EbayModel
conversations_metadata
class-attribute
instance-attribute
¶
conversations_metadata = Field(None, alias='conversationsMetadata', description='This container returns metadata from the call, such as how many conversations were updated, how many succeeded, and how many failed.')
conversations_response
class-attribute
instance-attribute
¶
conversations_response = Field(None, alias='conversationsResponse', description='This array returns a list of each conversation specified in the request and if the requested update was successful or failed.')
Error ¶
Bases: EbayModel
category
class-attribute
instance-attribute
¶
category = Field(None, description='Identifies the type of error.')
domain
class-attribute
instance-attribute
¶
domain = Field(None, description='Name for the primary system where the error occurred. This is relevant for application errors.')
error_id
class-attribute
instance-attribute
¶
error_id = Field(None, alias='errorId', description='A unique number to identify the error.')
input_ref_ids
class-attribute
instance-attribute
¶
input_ref_ids = Field(None, alias='inputRefIds', description='An array of request elements most closely associated to the error.')
long_message
class-attribute
instance-attribute
¶
long_message = Field(None, alias='longMessage', description='A more detailed explanation of the error.')
message
class-attribute
instance-attribute
¶
message = Field(None, description="Information on how to correct the problem, in the end user's terms and language where applicable.")
output_ref_ids
class-attribute
instance-attribute
¶
output_ref_ids = Field(None, alias='outputRefIds', description='An array of request elements most closely associated to the error.')
parameters
class-attribute
instance-attribute
¶
parameters = Field(None, description='An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.')
subdomain
class-attribute
instance-attribute
¶
subdomain = Field(None, description='Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc.')
MessageDetail ¶
Bases: EbayModel
created_date
class-attribute
instance-attribute
¶
created_date = Field(None, alias='createdDate', description='The date, in ISO 8601 format, the message was received.')
message_body
class-attribute
instance-attribute
¶
message_body = Field(None, alias='messageBody', description='The message text.')
message_id
class-attribute
instance-attribute
¶
message_id = Field(None, alias='messageId', description='The unique identifier of the message.')
message_media
class-attribute
instance-attribute
¶
message_media = Field(None, alias='messageMedia', description='This array returns a list, if applicable, of media attached to the message.')
read_status
class-attribute
instance-attribute
¶
read_status = Field(None, alias='readStatus', description='This boolean indicates if the message has been viewed by the recipient. If this boolean is returned as true , the message has been read. If this boolean is returned as false , the message has not been read.')
recipient_username
class-attribute
instance-attribute
¶
recipient_username = Field(None, alias='recipientUsername', description='The eBay username of the message recipient. 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 .')
sender_username
class-attribute
instance-attribute
¶
sender_username = Field(None, alias='senderUsername', description='The eBay username of the message sender. 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 .')
subject
class-attribute
instance-attribute
¶
subject = Field(None, description='The subject line of the message.')
ConversationDetail ¶
Bases: EbayModel
conversation_id
class-attribute
instance-attribute
¶
conversation_id = Field(None, alias='conversationId', description='The unique identifier of the conversation.')
conversation_status
class-attribute
instance-attribute
¶
conversation_status = Field(None, alias='conversationStatus', description='This value indicates the current status of the conversation, such as ACTIVE or ARCHIVED .')
conversation_title
class-attribute
instance-attribute
¶
conversation_title = Field(None, alias='conversationTitle', description='This value indicates the title of the conversation.')
conversation_type
class-attribute
instance-attribute
¶
conversation_type = Field(None, alias='conversationType', description='This value indicates the type of the conversation, such as FROM_EBAY or FROM_MEMBERS .')
created_date
class-attribute
instance-attribute
¶
created_date = Field(None, alias='createdDate', description='This value indicates the date the conversation was created in ISO 8601 format.')
latest_message
class-attribute
instance-attribute
¶
latest_message = Field(None, alias='latestMessage', description='This container returns the latest message in the conversation and its details.')
reference_id
class-attribute
instance-attribute
¶
reference_id = Field(None, alias='referenceId', description='This value indicates the reference ID associated with the corresponding referenceType value. In the case of a LISTING referenceType , this value will be the item ID value of the associated listing.')
reference_type
class-attribute
instance-attribute
¶
reference_type = Field(None, alias='referenceType', description='This value indicates the reference type, if applicable, associated with the conversation. The reference type is used to specify what the conversation is in reference to. For example, a value of LISTING specifies that the conversation is associated with a specific listing. The item ID associated with this listing will then be returned in the referenceId field.')
unread_count
class-attribute
instance-attribute
¶
unread_count = Field(None, alias='unreadCount', description='This value indicates the number of unread messages in the conversation.')
GetAllMyConversationsResponse ¶
Bases: EbayModel
conversations
class-attribute
instance-attribute
¶
conversations = Field(None, description='This array returns the conversations that match the filter criteria. Each conversation is returned with information such as its ID, status, title, type, and creation date, as well as the latest message in the conversation.')
href
class-attribute
instance-attribute
¶
href = Field(None, description='The URI to the current page of results.')
limit
class-attribute
instance-attribute
¶
limit = Field(None, description='The value of the limit parameter submitted in the request.')
next
class-attribute
instance-attribute
¶
next = Field(None, description='The URI for the next page of results. This value is returned if there is an additional page of results in the result set.')
offset
class-attribute
instance-attribute
¶
offset = Field(None, description='The value of the offset parameter submitted in the request.')
prev
class-attribute
instance-attribute
¶
prev = Field(None, description='The URI for the previous page of results. This value is only returned if there is a previous page of results in the result set.')
total
class-attribute
instance-attribute
¶
total = Field(None, description='The total number of entries returned in the result set.')
GetMessagesByConversationIdResponse ¶
Bases: EbayModel
conversation_status
class-attribute
instance-attribute
¶
conversation_status = Field(None, alias='conversationStatus', description='The current status of the conversation, such as ACTIVE or ARCHIVE .')
conversation_title
class-attribute
instance-attribute
¶
conversation_title = Field(None, alias='conversationTitle', description='The title of the conversation.')
conversation_type
class-attribute
instance-attribute
¶
conversation_type = Field(None, alias='conversationType', description='The type of the conversation, such as FROM_EBAY or FROM_MEMBERS .')
href
class-attribute
instance-attribute
¶
href = Field(None, description='The URI to the current page of results.')
limit
class-attribute
instance-attribute
¶
limit = Field(None, description='The value of the limit parameter submitted in the request.')
messages
class-attribute
instance-attribute
¶
messages = Field(None, description='This array returns a list of messages from the specified conversation.')
next
class-attribute
instance-attribute
¶
next = Field(None, description='The URI for the next page of results. This value is only returned if there is an additional page of results in the result set.')
offset
class-attribute
instance-attribute
¶
offset = Field(None, description='The value of the offset parameter submitted in the request.')
prev
class-attribute
instance-attribute
¶
prev = Field(None, description='The URI for the previous page of results. This value is only returned if there is a previous page of results in the result set.')
total
class-attribute
instance-attribute
¶
total = Field(None, description='The total number of entries returned in the result set.')