# Amazon Selling Partner

{% hint style="info" %}
The following documentation is for **Amazon Selling Partner v2.0.1** *(BDK)*.
{% endhint %}

## Overview

Amazon Selling Partner connects you to Amazon's marketplace to automate order retrieval and processing. This integration allows you to pull order data from your Amazon seller account and integrate it seamlessly into your workflows.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Amazon Selling Partner**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using Refresh Token, Client ID and Client Secret

Connect to Amazon Selling Partner API using LWA OAuth credentials.

| Label         | Description                                              | Type        |
| ------------- | -------------------------------------------------------- | ----------- |
| Refresh Token | LWA refresh token from Seller Central                    | `sensitive` |
| Client ID     | LWA client ID (starts with amzn1.application-oa2-client) | `text`      |
| Client Secret | LWA client secret                                        | `sensitive` |

## Procedures

### to retrieve (orders)

Retrieve orders from Amazon Selling Partner API.

**Input Concepts**

| Concept        | Description                                                               | Type                                                                                                    | Required | Default Value                                               |
| -------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- |
| `marketplace`  | Amazon marketplace (e.g., US, CA, GB)                                     | `enum[ae, au, be, br, ca, de, eg, es, fr, gb, in, it, jp, mx, nl, pl, sa, sandbox, se, sg, tr, us, za]` | No       | {'class\_name': 'Marketplace', 'name': 'US', 'value': 'US'} |
| `createdafter` | Filter orders created after this date (e.g., "2024-11-01T00:00:00Z")      | `text`                                                                                                  | No       | (no default)                                                |
| `last updated` | Filter orders last updated after this date (e.g., "2024-11-01T00:00:00Z") | `text`                                                                                                  | No       | (no default)                                                |

**Output Concepts**

| Concept                   | Description           | Type           |
| ------------------------- | --------------------- | -------------- |
| [`orders`](#amazon-order) | List of Order objects | `amazon order` |

**Examples**

Get orders created after a specific date

```generic
retrieve orders from amazon selling partner with
    the marketplace is "US"
    the createdafter is "2024-11-01T00:00:00Z"
    the limit is 100
```

Get orders last updated after a specific date

```generic
retrieve orders from amazon selling partner with
    the marketplace is "US"
    the last updated is "2024-11-01T00:00:00Z"
```

### to retrieve an (order) from *amazon selling partner*

Retrieve order details from Amazon Selling Partner API.

**Input Concepts**

| Concept       | Description                                               | Type                                                                                                    | Required | Default Value |
| ------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------- | ------------- |
| `marketplace` | Amazon marketplace (e.g., US, CA, GB)                     | `enum[ae, au, be, br, ca, de, eg, es, fr, gb, in, it, jp, mx, nl, pl, sa, sandbox, se, sg, tr, us, za]` | Yes      | (no default)  |
| `order id`    | The Amazon order identifier (e.g., "123-4567890-1234567") | `text`                                                                                                  | Yes      | (no default)  |

**Output Concepts**

| Concept                  | Description                                 | Type           |
| ------------------------ | ------------------------------------------- | -------------- |
| [`order`](#amazon-order) | Order object with all available information | `amazon order` |

**Examples**

Get a specific order by ID

```generic
retrieve an order from amazon selling partner with
    the marketplace is "US"
    the order id is "902-3159896-1390916"
```

Get order and check status

```generic
retrieve an order from amazon selling partner with
    the marketplace is "US"
    the order id is the customer order number
if the order's order status is "Pending"
    show "Order is pending"
```

Get order and extract buyer email

```generic
retrieve an order from amazon selling partner with
    the marketplace is "US"
    the order id is "123-4567890-1234567"
show the order's buyer info's buyer email
```

## Concepts

### Amazon order

Amazon Selling Partner order information.

| Field Name                                                                               | Description                               | Type                     |
| ---------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------ |
| `amazon_order_id`                                                                        | The unique Amazon order identifier.       | `text`                   |
| `order_status`                                                                           | The current status of the order.          | `text`                   |
| `purchase_date`                                                                          | The date when the order was purchased.    | `text`                   |
| `last_update_date`                                                                       | The date when the order was last updated. | `text`                   |
| `marketplace_id`                                                                         | The Amazon marketplace identifier.        | `optional[text]`         |
| `fulfillment_channel`                                                                    | The fulfillment channel (e.g., MFN, AFN). | `optional[text]`         |
| `order_type`                                                                             | The type of order.                        | `optional[text]`         |
| `shipment_service_level_category`                                                        | The shipment service level category.      | `optional[text]`         |
| `earliest_ship_date`                                                                     | The earliest ship date.                   | `optional[text]`         |
| `latest_ship_date`                                                                       | The latest ship date.                     | `optional[text]`         |
| `earliest_delivery_date`                                                                 | The earliest delivery date.               | `optional[text]`         |
| `latest_delivery_date`                                                                   | The latest delivery date.                 | `optional[text]`         |
| [`shipping_address`](#shipping_address-amazon-order)                                     | The shipping address.                     | `optional[json]`         |
| [`default_ship_from_location_address`](#default_ship_from_location_address-amazon-order) | The default ship from location address.   | `optional[json]`         |
| `number_of_items_shipped`                                                                | The number of items shipped.              | `optional[number]`       |
| `number_of_items_unshipped`                                                              | The number of items unshipped.            | `optional[number]`       |
| `payment_method`                                                                         | The payment method.                       | `optional[text]`         |
| `payment_method_details`                                                                 | List of payment method details.           | `optional[list of text]` |
| [`buyer_info`](#buyer_info-amazon-order)                                                 | Buyer information.                        | `optional[json]`         |
| `is_business_order`                                                                      | Whether this is a business order.         | `optional[boolean]`      |
| `is_prime`                                                                               | Whether this is a Prime order.            | `optional[boolean]`      |
| `is_global_express_enabled`                                                              | Whether global express is enabled.        | `optional[boolean]`      |
| `is_premium_order`                                                                       | Whether this is a premium order.          | `optional[boolean]`      |
| `is_sold_by_ab`                                                                          | Whether sold by Amazon Business.          | `optional[boolean]`      |
| `is_iba`                                                                                 | Whether this is an IBA order.             | `optional[boolean]`      |
| `is_ispu`                                                                                | Whether this is an ISPU order.            | `optional[boolean]`      |
| `is_access_point_order`                                                                  | Whether this is an access point order.    | `optional[boolean]`      |
| [`fulfillment_instruction`](#fulfillment_instruction-amazon-order)                       | Fulfillment instructions.                 | `optional[json]`         |
| [`automated_shipping_settings`](#automated_shipping_settings-amazon-order)               | Automated shipping settings.              | `optional[json]`         |
| `sales_channel`                                                                          | The sales channel.                        | `optional[text]`         |
| `order_channel`                                                                          | The order channel.                        | `optional[text]`         |
| `ship_service_level`                                                                     | The ship service level.                   | `optional[text]`         |
| `order_total`                                                                            | The order total amount.                   | `optional[json]`         |
| `payment_execution_detail`                                                               | Payment execution details.                | `optional[list of json]` |

**Concept attribute specifications**

**shipping\_address (amazon order)**

| Name              | Type             |
| ----------------- | ---------------- |
| `name`            | `optional[text]` |
| `address_line1`   | `optional[text]` |
| `address_line2`   | `optional[text]` |
| `address_line3`   | `optional[text]` |
| `city`            | `optional[text]` |
| `county`          | `optional[text]` |
| `district`        | `optional[text]` |
| `state_or_region` | `optional[text]` |
| `municipality`    | `optional[text]` |
| `postal_code`     | `optional[text]` |
| `country_code`    | `optional[text]` |
| `phone`           | `optional[text]` |
| `address_type`    | `optional[text]` |

**default\_ship\_from\_location\_address (amazon order)**

| Name              | Type             |
| ----------------- | ---------------- |
| `name`            | `optional[text]` |
| `address_line1`   | `optional[text]` |
| `address_line2`   | `optional[text]` |
| `address_line3`   | `optional[text]` |
| `city`            | `optional[text]` |
| `county`          | `optional[text]` |
| `district`        | `optional[text]` |
| `state_or_region` | `optional[text]` |
| `municipality`    | `optional[text]` |
| `postal_code`     | `optional[text]` |
| `country_code`    | `optional[text]` |
| `phone`           | `optional[text]` |
| `address_type`    | `optional[text]` |

**buyer\_info (amazon order)**

| Name                    | Type             |
| ----------------------- | ---------------- |
| `buyer_email`           | `optional[text]` |
| `buyer_name`            | `optional[text]` |
| `buyer_county`          | `optional[text]` |
| `buyer_tax_info`        | `optional[json]` |
| `purchase_order_number` | `optional[text]` |

**fulfillment\_instruction (amazon order)**

| Name                           | Type             |
| ------------------------------ | ---------------- |
| `fulfillment_supply_source_id` | `optional[text]` |

**automated\_shipping\_settings (amazon order)**

| Name                              | Type                |
| --------------------------------- | ------------------- |
| `has_automated_shipping_settings` | `optional[boolean]` |
| `automated_carrier`               | `optional[text]`    |
| `automated_ship_method`           | `optional[text]`    |