REST

FeedAMP Order Source API

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:

$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:

$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.