> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/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.

> Documentation for Feedonomics — the enterprise product feed management platform

## Docs

- [FeedAMP Order Source API](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api.md): Enable marketplaces to create orders in FeedAMP and retrieve fulfillment updates

## API Docs

- API Reference > Authentication [OAuth Authorization](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/authentication/oauth.md)
- API Reference > Authentication [Access Token](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/authentication/refresh-seller-access-token.md)
- API Reference > Orders [Get Orders](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/orders/get-orders.md)
- API Reference > Orders [Get Order](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/orders/get-order.md)
- API Reference > Orders [Place Order](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/orders/create-orders.md)
- API Reference > Orders [Get Fulfillments](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/orders/get-order-fulfillment-by-order-id.md)
- API Reference > Orders [Report Errors](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/orders/create-order-error.md)
- API Reference > Refunds [Get Seller Initiated Refunds](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/refunds/get-orders-refunds.md)
- API Reference > Refunds [Get Seller Initiated Refunds for an order](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/refunds/get-order-refunds.md)
- API Reference > Refunds [Get Seller Initiated Refunds for order](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/refunds/get-order-refund-by-id.md)
- API Reference > Refunds [Mark the refund as complete](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/refunds/update-order-refund-status.md)
- API Reference > Refunds [Report errors encountered when processing a seller-initiated refund](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/refunds/report-refund-error.md)
- API Reference > Returns [Get returns](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/returns/get-returns.md)
- API Reference > Returns [Get returns for an order](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/returns/get-order-returns.md)
- API Reference > Returns [Get return](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/returns/get-order-return.md)
- API Reference > Returns [Create a return](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/returns/create-order-returns.md)
- API Reference > Returns [Get the refunded amounts for the return](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/returns/get-return-refunds.md)
- API Reference > Returns [Mark the return as complete](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/returns/update-return-status.md)
- API Reference > Returns [Report errors encountered when processing the return refund](https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/returns/report-return-error.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.feedonomics.com/openapi.json)
- [OpenAPI YAML](https://docs.feedonomics.com/openapi.yaml)