Onboarding Step 4: Create your request

This onboarding section covers the steps on how to create an Amazon Business API request. Before you proceed, make sure that you've created an app client on Solution Provider Portal (SPP) and generated an access token and refresh token for your app client.

Step 1. Construct an Amazon Business API URI

Here are the components of an Amazon Business API URI.

Name	Description	Example
HTTP method	One of the Amazon Business API HTTP methods.	`GET`
Endpoint	An Amazon Business API Endpoint.	https://na.business-api.amazon.com
Path	The Amazon Business API section/version. number of the section/resource.	`/example/2020-08-26/foo`
Query string	The query parameters.	`?bar=bar\_value`
Path parameter	The path parameters.	`fooId`

Example:

PUT https://na.business-api.amazon.com/example/2020-08-26/fooId?bar=bar_value

Step 2. Add headers to the URI

Add headers to the URI that you constructed in Step 1. Construct an Amazon Business API URI.
Here are the HTTP headers you've included in the requests.

Request headers

Name	Description
`host`	The marketplace endpoint. Refer to Amazon Business API HTTP methods.
`x-amz-access-token`	The LWA access token. Refer to Onboarding Step 3: Authorizing Amazon Business API apps.
`x-amz-date`	The date and time of your request.
`user-agent`	Your application name and version number, platform, and programming language. These help Amazon diagnose and fix problems you might encounter with the service.

Here's an example of a request to the Amazon Business API with URI and headers.

GET example/2020-08-26/fooId?bar=bar_value HTTP/1.1
 host: na.business-api.amazon.com
 user-agent: My Amazon Business Application Tool/2.0 (Language=Java/1.8.0.221;Platform=Windows/10)
 x-amz-access-token=Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSREXAMPLE
 x-amz-date: 20190430T123600Z

Response format

In response to an HTTP request, Amazon Business Partner API returns response headers and a JSON response message.

Response headers

Name	Description
`Content-Length`	Standard HTTP response header.
`Content-Type`	Standard HTTP response header.
`Date`	Standard HTTP response header.
`x-amzn-RequestId`	Request identifier. Include this if you contact us for support.

Success Response

If your request is successful, Amazon Business API returns the data requested.

HTTP/1.1 200 OK
Content-Length: 368
Content-Type: application/json
Date: Thu, 01 Jun 2020 22:23:31 GMT
x-amzn-RequestId: 6875f61f-6aa1-11e8-98c6-9bExample
{
  "payload": {
    "example_response_attribute": "2020-04-23"
  }
}

Error response

If your request is unsuccessful, Amazon Business API returns an error response.

Response message

Element	Description	Required
`code`	Error code provided in API definition	Yes
`message`	Explanation of the error condition.	Yes
`details`	Link to additional information.	No

Here's an example of an error response.

HTTP/1.1 400 Bad Request
Content-Length: 117
Content-Type: application/json
Date: Fri, 01 Jun 2020 21:48:02 GMT
x-amzn-ErrorType: ValidationException
x-amzn-RequestId: a8c8d99a-6ab5-11e8-b0f8-19363980175b
{
  "errors": [
    {
      "message": "Access to requested resource is denied.",
      "code": "Unauthorized",
      "details": "Access token is missing in the request header."
    }
  ]
}

HTTP methods

Amazon Business API support these HTTP methods.

HTTP method	Description
`GET`	Retrieves resource data or a list of resources.
`POST`	Submits an entity to the specified resource, often causing a change in state or side effects on the server.
`PUT`	Replaces all current representations of the target resource with the request payload.