Messaging API v1 Use Case Guide

GET https://sellingpartnerapi-na.amazon.com/messaging/v1/orders/902-6786204-8179805?marketplaceIds=ATVPDKIKX0DER

{
  "_links":
  {
    "actions": [
      {
        "href": "/messaging/v1/orders/902-6786204-
8179805/messages/confirmCustomizationDetails?marketplaceIds=ATVPDKIKX0
DER",
        "name": "confirmCustomizationDetails"
      },
      {
        "href": "/messaging/v1/orders/902-6786204-
8179805/messages/negativeFeedbackRemoval?marketplaceIds=ATVPDKIKX0DER"
,
        "name": "negativeFeedbackRemoval"
      },
      {
        "href": "/messaging/v1/orders/902-6786204-
8179805/messages/confirmOrderDetails?marketplaceIds=ATVPDKIKX0DER",
        "name": "confirmOrderDetails"
      },
    ],
    "self":
    {
      "href": "/messaging/v1/orders/902-6786204-
8179805?marketplaceIds=ATVPDKIKX0DER"
    }
  },
  "_embedded":
  {
    "actions": [
      {
        "_links":
{
          "schema":
          {
            "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails/schema",
            "name": "confirmCustomizationDetails"
          },
          "self":
          {
            "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails?marketplaceIds=ATVPDKIKX0DER",
            "name": "confirmCustomizationDetails"
          }
        },
        "_embedded":
        {
          "schema":
          {
            "_links":
            {
              "self":
              {
                "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails/schema",
                "name": "confirmCustomizationDetails"
              }
            },
            "type": "object",
            "name": "confirmCustomizationDetails",
            "title": "Confirm customization details",
            "description": "Ask your customer to provide details or verify the customization input provided (name spelling, imagery, initials).",
            "properties":
            {
              "attachments":
              {
                "type": "array",
                "items":
                {
                  "type": "object",
                  "required": [],
                  "properties":
                  {
                    "fileName":
                    {
                      "type": "string"
                    },
                    "id":
                    {
                      "type": "string"
}
                  }
                },
                "title": "Add attachment",
                "description": "You can upload text files, PDFs, Word documents, and these image file types: .jpg, .gif, and .png. The total size of attachments must be less than 10 MB.",
                "x-ui-field-type": "attachments",
                "maxItems": 5
              },
              "rawMessageBody":
              {
                "type": "string",
                "title": "Explain why you are contacting and any action you need your customer to take. ",
                "description": "800 character limit. Only links related to order completion are allowed, no HTML or email addresses.",
                "x-ui-field-type": "text",
                "minLength": 1,
                "maxLength": 800
              }
            },
            "required": [
              "attachments",
              "rawMessageBody"
            ],
            "$schema": "http://json-schema.org/draft-04/schema#",
            "x-ui-hidden": null
          }
        },
        "name": "confirmCustomizationDetails",
        "title": "Confirm customization details"
      },
      {
        "_links":
        {
          "schema":
          {
            "href": "/messaging/v1/orders/902-6786204-8179805/messages/negativeFeedbackRemoval/schema",
            "name": "negativeFeedbackRemoval"
          },
          "self":
          {
            "href": "/messaging/v1/orders/902-6786204-8179805/messages/negativeFeedbackRemoval?marketplaceIds=ATVPDKIKX0DER",
            "name": "negativeFeedbackRemoval"
          }
        },
        "_embedded":
        {
"schema":
          {
            "_links":
            {
              "self":
              {
                "href": "/messaging/v1/orders/902-6786204-8179805/messages/negativeFeedbackRemoval/schema",
                "name": "negativeFeedbackRemoval"
              }
            },
            "type": "object",
            "name": "negativeFeedbackRemoval",
            "title": "Request to update negative feedback",
            "description": "Ask your customer to consider updating their seller feedback rating. You may only send this once per order.",
            "properties": {},
            "required": [],
            "$schema": "http://json-schema.org/draft-04/schema#",
            "x-ui-hidden": true
          }
        },
        "name": "negativeFeedbackRemoval",
        "title": "Request to update negative feedback"
      },
      {
        "_links":
        {
          "schema":
          {
            "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmOrderDetails/schema",
            "name": "confirmOrderDetails"
          },
          "self":
          {
            "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmOrderDetails?marketplaceIds=ATVPDKIKX0DER",
            "name": "confirmOrderDetails"
          }
        },
        "_embedded":
        {
          "schema":
          {
            "_links":
            {
              "self":
              {
                "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmOrderDetails/schema",
                "name": "confirmOrderDetails"
}
            },
            "type": "object",
            "name": "confirmOrderDetails",
            "title": "Confirm order details",
            "description": "Ask your customer a specific order-related question prior to shipping their order.",
            "properties":
            {
              "rawMessageBody":
              {
                "type": "string",
                "title": "Explain why you are contacting and any action you need your customer to take. ",
                "description": "2000 character limit. Only links related to order completion are allowed, no HTML or email addresses.",
                "x-ui-field-type": "text",
                "minLength": 1,
                "maxLength": 2000
              }
            },
            "required": [
              "rawMessageBody"
            ],
            "$schema": "http://json-schema.org/draft-04/schema#",
            "x-ui-hidden": null
          }
        },
        "name": "confirmOrderDetails",
        "title": "Confirm order details"
      },
    ]
  }
}

package io.swagger.client.util;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.DigestInputStream;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public class CreateMD5
{

  public static String computeContentMD5Value(FileInputStream fis)
  throws IOException,
  NoSuchAlgorithmException
  {

    DigestInputStream dis = new DigestInputStream(fis,
        MessageDigest.getInstance("MD5"));

    byte[]buffer = new byte[8192];
    while (dis.read(buffer) > 0);

    String md5Content = new String(org.apache.commons.codec.binary.Base64
        .encodeBase64(dis.getMessageDigest().digest()));

    // Effectively resets the stream to be beginning of the file
    // via a FileChannel.
    fis.getChannel().position(0);

    return md5Content;
  }
}

POST https://sellingpartnerapi-na.amazon.com/uploads/2020-11-01/uploadDestinations/messaging/v1/orders/7XX-5XXXXX-8XXXXXX/messages/invoice?marketplaceIds=A2Q3Y263D00KWC&contentMD5=qCcR3o%2BU0FUR1%2BgXhApNfQ%3D%3D

{
  "payload":
  {
    "uploadDestinationId": "sc/7ae2d3b1-fdd3-42c4-98c4-9cc509fb95d8.png",
    "url": "https://aplus-media.s3.amazonaws.com/?x-amz-date=20201116T184623Z&x-amz-signature=c5c8efd95d883b6787a2b1a93c7c066f01cb4e8d7be3ece4360aa800332e0cf9&x-amz-meta-owner=A2CZ04NGKYDXDV&acl=private&key=sc/7ae2d3b1-fdd3-42c4-98c4-9cc509fb95d8.png&x-amz-algorithm=AWS4-HMAC-SHA256&policy=eyJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJhcGx1cy1tZWRpYS1iZXRhIn0seyJrZXkiOiJzb3RhLzdhZTJkM2IxLWZkZDMtNDJjNC05OGM0LTljYzUwOWZiOTVkOC5wbmcifSx7ImFjbCI6InByaXZhdGUifSx7IngtYW16LW1ldGEtb3duZXIiOiJBMkNaMDROR0tZRFhEViJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsieC1hbXotY3JlZGVudGlhbCI6IkFLSUE2TDZSN1FFNTZGNkdNRzVFLzIwMjAxMTE2L3VzLWVhc3QtMS9zMy9hd3M0X3JlcXVlc3QifSx7IngtYW16LWRhdGUiOiIyMDIwMTExNlQxODQ2MjNaIn0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMSwzMTQ1NzI4XV0sImV4cGlyYXRpb24iOiIyMDIwLTExLTE2VDIxOjQ2OjIzLjg2OFoifQ==&x-amz-credential=AKIA6L6R7QE56F6GMG5E/20201116/us-east-1/s3/aws4_request",
    "headers":
    {
      "Content-MD5": "1jnGuPv7xwPiat6NesKL/w=="
    }
  }
}

package io.swagger.client.util;

import java.io.IOException;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Map;

import io.swagger.client.model.CreateUploadDestinationResponse;

public class UploadFileToDestination
{

  private static String requestMethod = "PUT";
  private static String contentType = "Content-Type";
  private static String contentValue = "application/text";
  private static URL url;
  private static Map < String,
  String > headers;

  /* Upload file to destination using the response returned in
  CreateUploadDestination. Reference https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObjectJavaSDK.html)
   */

 
  public static void uploadFileInDestination(
    CreateUploadDestinationResponse uploadDestinationPayload)
  throws IOException
  {

    url = new URL(uploadDestinationPayload.getPayload().getUrl());
    headers = (Map < String, String > )uploadDestinationPayload.getPayload()
    .getHeaders();

    // Create the connection and use it to upload the new object using the
    // pre-signed URL.
    HttpURLConnection connection = (HttpURLConnection)url.openConnection();
    connection.setDoOutput(true);
    connection.setRequestMethod(requestMethod);
    connection.setRequestProperty(contentType, contentValue);
    // headers that are returned in createDestination call
    for (Map.Entry < String, String > headersEntry: headers.entrySet())
    {
      connection.setRequestProperty(headersEntry.getKey(),
        headersEntry.getValue());
    }
    OutputStreamWriter out = new OutputStreamWriter(
        connection.getOutputStream());
    out.write("Text of the file");
    out.close();
    // Check the HTTP response code. To complete the upload and make the
    // object available,
    // you must interact with the connection object in some way.
    connection.getResponseCode();
    System.out.println("HTTP response code: " + connection.getResponseCode()
       + connection.getResponseMessage());
    connection.disconnect();
  }
}

POST https://sellingpartnerapi-na.amazon.com/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails?marketplaceIds=ATVPDKIKX0DER
{
  "text": "This is the message from the seller to the buyer that will appear in the email to the buyer.",
  "attachments": [
    {
      "uploadDestinationId": "4370d51b-2954-445c-9f30-EXAMPLE6b9de",
      "fileName": "example.txt"
    }
  ]
}