> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.feedonomics.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.feedonomics.com/_mcp/server.

# FeedAMP Order Source API

> Enable marketplaces to create orders in FeedAMP and retrieve fulfillment updates

## Overview

The API allows marketplaces to:

* Place an order into a seller's account in FeedAMP
* Query seller's marketplace orders for fulfillment information
* Report validation errors for seller's fulfillment information
* Update the marketplace's status for an order

## Expected Usage

* Marketplaces must place orders into the appropriate seller's account using the PUT `/orders/{mp_order_number}` endpoint.
* Each order must have a valid marketplace state when being placed into or updated in FeedAMP:
  * **PENDING** - Order is still awaiting payment or other finalization before being eligible for fulfillment
  * **AWAITING_SHIPMENT** - Order has cleared payment and cancellation window, if any (e.g. \~30 minutes from purchase time), and requires fulfillment from the seller.
  * **SHIPPED** - Order has all required fulfillment information from the seller and the marketplace considers the order complete.
  * **CANCELLED** - Order has been cancelled by the marketplace AFTER having been placed into FeedAMP.
* Marketplaces must regularly poll the seller's account to retrieve order fulfillment information, using a timely interval.
  * Obtain info for a batch of orders by calling the GET `/orders` endpoint. For efficient searching, you can filter based on the last time the fulfillment was updated and/or by fulfillment status.
  * Obtain info for a single order by calling either the GET `/orders/{mp_order_number}` or GET `/orders/{mp_order_number}/fulfillments` endpoint.
* If the marketplace finds issues with the seller's fulfillment information for an order, the marketplace must report the appropriate error(s) for the order using the POST `/orders/{mp_order_number}/errors` endpoint.
* When the marketplace has successfully processed all the fulfillments for an order, the order's status must be updated to reflect the marketplace state (e.g. SHIPPED, CANCELLED) using the PUT `/orders/{mp_order_number}` endpoint.

## Authentication

Access to the API is granted by supplying a valid access token, associated with a seller's account, in the Authorization header field of your requests.

To generate an access token, you will need a Client ID and Client Secret (provided by Feedonomics). You will also need a one-time-use authorization code returned to the callback url via the OAuth authorization process `/authorization`, or a valid refresh token obtained from the response to a previous call to POST `/access_token`.

To obtain the authorization code, the seller will need to Authorize access to their account in FeedAMP. The seller should be directed to the authorization url:

```
https://DOMAIN/authorize?response_type=code&client_id=CLIENT_ID&redirect_url=CALLBACK_URL&state=STATE
```

When the authorization is complete the seller will be redirected to:

```
CALLBACK_URL?code=AUTH_CODE&state=STATE
```

When using a one-time authorization code, call the access token endpoint with the "authorization_code" grant type:

```bash
curl -X POST "https://DOMAIN/access_token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET"
```

When using a refresh token, call the access token endpoint with the "refresh_token" grant type:

```bash
curl -X POST "https://DOMAIN/access_token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET"
```

Access tokens expire after 1 hour. Refresh tokens expire after 1 year.