Selling Partner API for Messaging (v1)

Download OpenAPI specification:Download

URL: https://sellercentral.amazon.com/gp/mws/contactus.html

With the Messaging API you can build applications that send messages to buyers. You can get a list of message types that are available for an order that you specify, then call an operation that sends a message to the buyer for that order. The Messaging API returns responses that are formed according to the JSON Hypertext Application Language (HAL) standard.

messaging

getMessagingActionsForOrder

Returns a list of message types that are available for an order that you specify. A message type is represented by an actions object, which contains a path and query parameter(s). You can use the path and parameter(s) to call an operation that sends a message.

Usage Plan:

Rate (requests per second)	Burst
1	5

For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which you want a list of available message types.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Responses

Response samples

Content type

application/hal+json

{"_links": {"actions": [{"href": "/messaging/v1/orders/903-1671087-0812628/messages/negativeFeedbackRemoval?marketplaceIds=ATVPDKIKX0DER",
"name": "negativeFeedbackRemoval"
}
],
"self": {"href": "/messaging/v1/orders/903-1671087-0812628?marketplaceIds=ATVPDKIKX0DER"
}
},
"_embedded": {"actions": [{"_links": {"schema": {"href": "/messaging/v1/orders/903-1671087-0812628/messages/negativeFeedbackRemoval/schema",
"name": "negativeFeedbackRemoval"
},
"self": {"href": "/messaging/v1/orders/903-1671087-0812628/messages/negativeFeedbackRemoval?marketplaceIds=ATVPDKIKX0DER",
"name": "negativeFeedbackRemoval"
}
}
}
]
}
}

confirmCustomizationDetails

Sends a message asking a buyer to provide or verify customization details such as name spelling, images, initials, etc.

Usage Plan:

Rate (requests per second)	Burst
1	5

For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Request Body schema: application/json

text	string [ 1 .. 800 ] characters The text to be sent to the buyer. Only links related to customization details are allowed. Do not include HTML or email addresses. The text must be written in the buyer's language of preference, which can be retrieved from the GetAttributes operation.
	Array of objects (Attachment) Attachments to include in the message to the buyer.

Responses

Request samples

Payload

Content type

application/json

{"text": "string",
"attachments": [{"uploadDestinationId": "string",
"fileName": "string"
}
]
}

Response samples

Content type

application/hal+json

{"errors": [{"code": "string",
"message": "string",
"details": "string"
}
]
}

createConfirmDeliveryDetails

Sends a message to a buyer to arrange a delivery or to confirm contact information for making a delivery.

Usage Plan:

Rate (requests per second)	Burst
1	5

For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Request Body schema: application/json

text	string [ 1 .. 2000 ] characters The text to be sent to the buyer. Only links related to order delivery are allowed. Do not include HTML or email addresses. The text must be written in the buyer's language of preference, which can be retrieved from the GetAttributes operation.

Responses

Request samples

Payload

Content type

application/json

{"text": "string"
}

Response samples

Content type

application/hal+json

{"errors": [{"code": "string",
"message": "string",
"details": "string"
}
]
}

createLegalDisclosure

Sends a critical message that contains documents that a seller is legally obligated to provide to the buyer. This message should only be used to deliver documents that are required by law.

Usage Plan:

Rate (requests per second)	Burst
1	5

For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Request Body schema: application/json

Array of objects (Attachment)

Attachments to include in the message to the buyer. If any text is included in the attachment, the text must be written in the buyer's language of preference, which can be retrieved from the GetAttributes operation.

Responses

Request samples

Payload

Content type

application/json

{"attachments": [{"uploadDestinationId": "string",
"fileName": "string"
}
]
}

Response samples

Content type

application/hal+json

{"errors": [{"code": "string",
"message": "string",
"details": "string"
}
]
}

createNegativeFeedbackRemoval

Sends a non-critical message that asks a buyer to remove their negative feedback. This message should only be sent after the seller has resolved the buyer's problem.

Usage Plan:

Rate (requests per second)	Burst
1	5

For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Responses

Response samples

Content type

application/hal+json

{"errors": [{"code": "string",
"message": "string",
"details": "string"
}
]
}

createConfirmOrderDetails

Sends a message to ask a buyer an order-related question prior to shipping their order.

Usage Plan:

Rate (requests per second)	Burst
1	5

For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Request Body schema: application/json

text	string [ 1 .. 2000 ] characters The text to be sent to the buyer. Only links related to order completion are allowed. Do not include HTML or email addresses. The text must be written in the buyer's language of preference, which can be retrieved from the GetAttributes operation.

Responses

Request samples

Payload

Content type

application/json

{"text": "string"
}

Response samples

Content type

application/hal+json

{"errors": [{"code": "string",
"message": "string",
"details": "string"
}
]
}

createConfirmServiceDetails

Sends a message to contact a Home Service customer to arrange a service call or to gather information prior to a service call.

Usage Plan:

Rate (requests per second)	Burst
1	5

For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Request Body schema: application/json

text	string [ 1 .. 2000 ] characters The text to be sent to the buyer. Only links related to Home Service calls are allowed. Do not include HTML or email addresses. The text must be written in the buyer's language of preference, which can be retrieved from the GetAttributes operation.

Responses

Request samples

Payload

Content type

application/json

{"text": "string"
}

Response samples

Content type

application/hal+json

{"errors": [{"code": "string",
"message": "string",
"details": "string"
}
]
}

CreateAmazonMotors

Sends a message to a buyer to provide details about an Amazon Motors order. This message can only be sent by Amazon Motors sellers.

Usage Plan:

Rate (requests per second)	Burst
1	5

For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Request Body schema: application/json

Array of objects (Attachment)

Attachments to include in the message to the buyer. If any text is included in the attachment, the text must be written in the buyer's language of preference, which can be retrieved from the GetAttributes operation.

Responses

Request samples

Payload

Content type

application/json

{"attachments": [{"uploadDestinationId": "string",
"fileName": "string"
}
]
}

Response samples

Content type

application/hal+json

{"errors": [{"code": "string",
"message": "string",
"details": "string"
}
]
}

CreateWarranty

Sends a message to a buyer to provide details about warranty information on a purchase in their order.

Usage Plan:

Rate (requests per second)	Burst
1	5

For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Request Body schema: application/json

	Array of objects (Attachment) Attachments to include in the message to the buyer. If any text is included in the attachment, the text must be written in the buyer's language of preference, which can be retrieved from the GetAttributes operation.
coverageStartDate	string <date-time> The start date of the warranty coverage to include in the message to the buyer.
coverageEndDate	string <date-time> The end date of the warranty coverage to include in the message to the buyer.

Responses

Request samples

Payload

Content type

application/json

{"attachments": [{"uploadDestinationId": "string",
"fileName": "string"
}
],
"coverageStartDate": "2019-08-24T14:15:22Z",
"coverageEndDate": "2019-08-24T14:15:22Z"
}

Response samples

Content type

application/hal+json

{"errors": [{"code": "string",
"message": "string",
"details": "string"
}
]
}

GetAttributes

Returns a response containing attributes related to an order. This includes buyer preferences.

Usage Plan:

Rate (requests per second)	Burst
1	5

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Responses

Response samples

Content type

application/hal+json

{"buyer": {"locale": "en-US"
}
}

createDigitalAccessKey

Sends a message to a buyer to share a digital access key needed to utilize digital content in their order.

Usage Plan:

Rate (requests per second)	Burst
1	5

For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Request Body schema: application/json

text	string [ 1 .. 400 ] characters The text to be sent to the buyer. Only links related to the digital access key are allowed. Do not include HTML or email addresses. The text must be written in the buyer's language of preference, which can be retrieved from the GetAttributes operation.
	Array of objects (Attachment) Attachments to include in the message to the buyer.

Responses

Request samples

Payload

Content type

application/json

{"text": "string",
"attachments": [{"uploadDestinationId": "string",
"fileName": "string"
}
]
}

Response samples

Content type

application/hal+json

{"errors": [{"code": "string",
"message": "string",
"details": "string"
}
]
}

createUnexpectedProblem

Sends a critical message to a buyer that an unexpected problem was encountered affecting the completion of the order.

Usage Plan:

Rate (requests per second)	Burst
1	5

For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Request Body schema: application/json

text	string [ 1 .. 2000 ] characters The text to be sent to the buyer. Only links related to unexpected problem calls are allowed. Do not include HTML or email addresses. The text must be written in the buyer's language of preference, which can be retrieved from the GetAttributes operation.

Responses

Request samples

Payload

Content type

application/json

{"text": "string"
}

Response samples

Content type

application/hal+json

{"errors": [{"code": "string",
"message": "string",
"details": "string"
}
]
}

sendInvoice

Sends a message providing the buyer an invoice

path Parameters

amazonOrderId

required

string

An Amazon order identifier. This specifies the order for which a message is sent.

query Parameters

marketplaceIds

required

Array of strings <= 1 items

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Request Body schema: application/json

Array of objects (Attachment)

Attachments to include in the message to the buyer.

Responses

Request samples

Payload

Content type

application/json

{"attachments": [{"uploadDestinationId": "string",
"fileName": "string"
}
]
}

Response samples

Content type

application/hal+json

{"errors": [{"code": "string",
"message": "string",
"details": "string"
}
]
}