FeedAMP Order Source API (0.2.0)

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, for example

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. Example:

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. Example:

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"

In either case, the response from the endpoint will contain a new access token, along with a refresh token to make a subsequent authorization call.

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