Checkout

The final step of using the Storefront API for Amazon Business is to add the product to the shopping cart.

caution

Our API does not perform the order, you need to redirect to the URL returned when Direct Order is disabled or use the returned Cart item to initiate the order process by your own.

The checkout process is sligly different if the Direct Order option is enabled for your account.

Direct Order enabled

If Direct Order is enabled for your account, you need to use an access token (YOUR_ACCESS_TOKEN) to authenticate your request. You will also need to pass the YOUR_PRODUCT_ID again to initiate the checkout process, together with an AMAZON_OFFER_ID, returned on the Product Details endpoint, and a positive QUANTITY.

cURL

curl --request POST \
     --header 'authorization: YOUR_ACCESS_TOKEN' \
     --url 'https://YOUR_DOMAIN/api/v1/amazon/products/YOUR_PRODUCT_ID/checkout'
     --data '{"amazonOfferId": "AMAZON_OFFER_ID", "quantity": QUANTITY}'

JavaScript

var axios = require("axios").default;

var options = {
  method: 'POST',
  url: 'https://YOUR_DOMAIN/api/v1/amazon/products/YOUR_PRODUCT_ID/checkout',
  headers: {
    'content-type': 'application/json',
    'authorization: bearer YOUR_ACCESS_TOKEN'
  },
  json: {
    amazonOfferId: "AMAZON_OFFER_ID",
    quantity: QUANTITY
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

C#

var client = new RestClient("https://YOUR_DOMAIN/api/v1/amazon/products/YOUR_PRODUCT_ID/checkout");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("authorization", "bearer YOUR_ACCESS_TOKEN");
request.AddStringBody(`{"amazonOfferId": "AMAZON_OFFER_ID", "quantity": QUANTITY}`, ContentType.Json)
IRestResponse response = client.Execute(request);

Java

HttpResponse<String> response = Unirest.post("https://YOUR_DOMAIN/api/v1/amazon/products/YOUR_PRODUCT_ID/checkout")
  .header("content-type", "application/json")
  .header("authorization", "bearer YOUR_ACCESS_TOKEN")
  .body("{\"amazonOfferId\": \"AMAZON_OFFER_ID\", \"quantity\": QUANTITY}")
  .asString();

Go

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io"
)

func main() {
    // Configure your URL
    url := "https://YOUR_DOMAIN"

    // Setup the request body
    var data = struct {
      AmazonOfferId string `json:"amazonOfferId"`
      Quantity float64 `json:"quantity"`
    }{
      AmazonOfferId: "AMAZON_OFFER_ID",
      Quantity: QUANTITY,
    }
    body, err := json.Marshal(data)
    if err != nil {
      panic(err)
    }
    requestBody := bytes.NewReader(body)

    // Prepare HTTP request
    req, err := http.NewRequest("POST", baseURL+"/api/v1/amazon/products/YOUR_PRODUCT_ID/checkout", requestBody)
    if err != nil {
        panic(err)
    }
    req.Header.Set("content-type", "application/json")
    req.Header.Set("authorization", "bearer "+YOUR_ACCESS_TOKEN)

    // Execute the request
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    // The HTTP response body will return JSON accordingly
    body, err := io.ReadAll(req.Body)
    if err != nil {
        panic(err)
    }
    fmt.Println(resp)
    fmt.Println(string(body))
}

Parameters

Parameter	Description
amazonOfferId	A current offer id returned by the product details endpoint.
quantity	Quantity to be added to reserved.

Response

If everything goes well, you will receive a successful HTTP response with status 200 OK with a payload containing a cart item that you can use to initiate the order by your own.

{
  "type": "direct-order",
  "item": {
    "id": 1000000043,
    "productId": "s_CgpCMDc5OEg0NkNNEAIaAkRFIgVlbi1HQii4hT0",
    "offerId": "DloG1%2BEdh%2F7zO1JBKctxp99vTXI5d2P5RAEZda1iy8dwbayrz8HeH8r1lf0nOy73CM4mEVL3aF0bLyGWFRAc8R77383LFqJ7ThaCYRAo3BWdJijsBZT8Xw5CtopQMaBxabXwZ%2F%2Bd3IvyCn2qrNsv%2B4yc8r0kDBip9zWIocM2MvRqmvhaFFdUeg%3D%3D",
    "vendorName": "Amazon Business",
    "catalogName": "Amazon Business (DE)",
    "sku": "B0798H46CM",
    "asin": "B0798H46CM",
    "name": "Apple iPhone 8 (refurbished), 64GB",
    "imageURL": "https://m.media-amazon.com/images/I/31RN1gbmjjL._SY500_.jpg",
    "quantity": 2,
    "canChangeQuantity": true,
    "price": {
      "amount": "119.99",
      "currency": "EUR"
    },
    "priceUnit": "per ",
    "priceQuantity": 1,
    "quantityMin": 1,
    "quantityMax": 4,
    "manufacturer": "Apple",
    "erpNumber": "AMAZON",
    "externalId": "DloG1%2BEdh%2F7zO1JBKctxp99vTXI5d2P5RAEZda1iy8dwbayrz8HeH8r1lf0nOy73CM4mEVL3aF0bLyGWFRAc8R77383LFqJ7ThaCYRAo3BWdJijsBZT8Xw5CtopQMaBxabXwZ%2F%2Bd3IvyCn2qrNsv%2B4yc8r0kDBip9zWIocM2MvRqmvhaFFdUeg%3D%3D",
    "unspsc": "43191501",
    "isService": false,
    "extProductId": "DloG1%2BEdh%2F7zO1JBKctxp99vTXI5d2P5RAEZda1iy8dwbayrz8HeH8r1lf0nOy73CM4mEVL3aF0bLyGWFRAc8R77383LFqJ7ThaCYRAo3BWdJijsBZT8Xw5CtopQMaBxabXwZ%2F%2Bd3IvyCn2qrNsv%2B4yc8r0kDBip9zWIocM2MvRqmvhaFFdUeg%3D%3D",
    "shippingTotals": {
      "amount": "0",
      "currency": "EUR"
    },
    "taxTotals": {
      "amount": "0",
      "currency": "EUR"
    }
  }
}

Direct Order disabled

If Direct Order is disabled for your account, you need to use an access token (YOUR_ACCESS_TOKEN) to authenticate your request. You will also need to pass the YOUR_PRODUCT_ID again to initiate the checkout process. Finally, we will need a YOUR_HOOK_URL that we will use to return the shopping cart to your system as it is returned by Amazon.

cURL

curl --request POST \
     --header 'authorization: YOUR_ACCESS_TOKEN' \
     --url 'https://YOUR_DOMAIN/api/v1/amazon/products/YOUR_PRODUCT_ID/checkout'
     --data '{"callbackUrl": "YOUR_HOOK_URL"}'

JavaScript

var axios = require("axios").default;

var options = {
  method: 'POST',
  url: 'https://YOUR_DOMAIN/api/v1/amazon/products/YOUR_PRODUCT_ID/checkout',
  headers: {
    'content-type': 'application/json',
    'authorization: bearer YOUR_ACCESS_TOKEN'
  },
  json: {
    callbackUrl: YOUR_HOOK_URL,
    name: "Joe Average",
    shipTo: {
      street: "...",
      city: "...",
      state: "...",
      postalCode: "...",
      countryCode: "...",
      country: "..."
    }
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

C#

var client = new RestClient("https://YOUR_DOMAIN/api/v1/amazon/products/YOUR_PRODUCT_ID/checkout");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("authorization", "bearer YOUR_ACCESS_TOKEN");
request.AddStringBody(`{"callbackUrl": YOUR_HOOK_URL}`, ContentType.Json)
IRestResponse response = client.Execute(request);

Java

HttpResponse<String> response = Unirest.post("https://YOUR_DOMAIN/api/v1/amazon/products/YOUR_PRODUCT_ID/punchout")
  .header("content-type", "application/json")
  .header("authorization", "bearer YOUR_ACCESS_TOKEN")
  .body("{\"callbackUrl\": YOUR_HOOK_URL}")
  .asString();

Go

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io"
)

func main() {
    // Configure your URL
    url := "https://YOUR_DOMAIN"

    // Setup the request body
    var data = struct {
      CallbackURL string `json:"callbackUrl,omitempty"`
    }{
      CallbackURL: YOUR_HOOK_URL,
    }
    body, err := json.Marshal(data)
    if err != nil {
      panic(err)
    }
    requestBody := bytes.NewReader(body)

    // Prepare HTTP request
    req, err := http.NewRequest("POST", baseURL+"/api/v1/amazon/products/YOUR_PRODUCT_ID/punchout", requestBody)
    if err != nil {
        panic(err)
    }
    req.Header.Set("content-type", "application/json")
    req.Header.Set("authorization", "bearer "+YOUR_ACCESS_TOKEN)

    // Execute the request
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    // The HTTP response body will return JSON accordingly
    body, err := io.ReadAll(req.Body)
    if err != nil {
        panic(err)
    }
    fmt.Println(resp)
    fmt.Println(string(body))
}

Parameters

Parameter	Description
callbackUrl	Set this to the URL you want Storefront to postback the shopping cart in OCI format.
name	(optional) Name of the shopper.
shipTo	(optional) Address that Amazon should use for sending the order.

Shipment address

The parameters of the shipment address are the same as those in the cXML specification.

Parameter	Description
addressId	(optional) ID of the address.
addressIdDomain	(optional) ID of the address.
street	(optional) ID of the address.
cityCode	(optional) ID of the address.
city	(optional) ID of the address.
stateCode	(optional) ID of the address.
state	(optional) ID of the address.
postalCode	(optional) ID of the address.
countryCode	(optional) ID of the address.
country	(optional) ID of the address.

Example:

<ShipTo>
  <!-- addressId and addressIdDomain -->
  <Address addressID="1000467">
    <!-- Name of the tenant -->
    <Name xml:lang="en">Example Inc.</Name>
    <PostalAddress>
      <!-- name -->
      <DeliverTo>Joe Average</DeliverTo>
      <Street>123 Main Street</Street>
      <City>Sunnyvale</City>
      <!-- stateCode and state -->
      <State isoStateCode="US-CA">CA</State>
      <PostalCode>94089</PostalCode>
      <!-- countryCode and country -->
      <Country isoCountryCode="US">United States</Country>
    </PostalAddress>
  </Address>
</ShipTo>

Response

If everything goes well, you will receive a successful HTTP response with status 200 OK with a payload containing a URL that you can send to the user agent to follow.

{
  "type": "cxml-punchout",
  "punchout": {
    "redirectUrl": "https://www.amazon.com/eprocurement/initiate-clean-punchout/123-4567890-1234567"
  }
}

Following this URL will bring the end-user to the detail page of the product she was looking at on your frontend.

Errors

In case of an error, you can use the HTTP status code and the response body to find out what went wrong.

HTTP Status Code	Description
400 Bad Request	The server understood your request but is unable to complete it, e.g. because a required parameter is missing.
401 Unauthorized	You sent invalid or expired credentials.
404 Not Found	The product, catalog, or vendor wasn't found.
500 Internal Server Error	Something went wrong on our side.