FeedAMP Order Source API (0.1.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.

Authentication

OAuth Authorization

Start of Oauth process a Seller's to authorize access to a marketplace in Feedamp.

Authorizations:
bearerAuth
query Parameters
response_type
required
string
Value: "code"

Specifies the OAuth authorization method. Only the Authorization code workflow is supported.

client_id
required
string

The account id given by Feedonomics as part of the onboarding process

state
required
string

A unique value provided for each authorization request. This value will be returned in the query parameters in the redirect_url so the request can be verified by the marketplace.

redirect_url
required
string
Example: redirect_url=https://domain.localhost/callback

The fully qualified url that the seller will be sent to once the Oauth Authorization workflow has been completed. The url will have the query parameters returning the authorization code and the provided state

Responses

Access Token

Get a new access token for a specific seller using a one-time authorization code or a valid refresh token

Authorizations:
bearerAuth
Request Body schema: application/json
grant_type
required
string
Enum: "authorization_code" "refresh_token"

The type of grant used for the request. If authorization_code is used, the authorization code must be sent via the code parameter. If refresh_token is used, the refresh token must be sent via the refresh_token parameter

code
string

Single-use authorization code, for requesting new tokens using the authorization_code grant type

refresh_token
string

A refresh_token obtained by a previous call to the POST /access_token endpoint, for requesting new tokens using the refresh_token grant type

client_id
required
string

The account id given to you by Feedonomics as part of the onboarding process

client_secret
required
string

A password associated with your client_id, given to you by Feedonomics as part of the onboarding process

Responses

Request samples

Content type
application/json
{
  • "grant_type": "refresh_token",
  • "code": "string",
  • "refresh_token": "string",
  • "client_id": "string",
  • "client_secret": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwibmFtZSI6IkZlZWRhbXAiLCJpYXQiOjF9._p278gl45T7hITPuson9KEiE-SMYwms3q-2DbAgiev8",
  • "token_type": "Bearer",
  • "refresh_token": "CLIENT_REFRESH_TOKEN",
  • "expires_in": 3600
}

Orders

Get Orders

Get all orders from FeedAMP for a seller, filtered by the provided query params

Authorizations:
bearerAuth
query Parameters
mp_order_numbers
Array of strings [ 1 .. 100 ] items

Comma-delimited list of marketplace order numbers

fulfillment_status
Array of strings non-empty
Items Enum: "UNFULFILLED" "PARTIALLY_FULFILLED" "COMPLETE"

Comma-delimited list of fulfillment statuses

  • UNFULFILLED returns orders that are AWAITING_SHIPMENT with no fulfillments
  • PARTIALLY_FULFILLED returns orders that are AWAITING_SHIPMENT and have at least one fulfillment
  • COMPLETE returns orders that have all of their fulfillments, and have been marked SHIPPED or CANCELLED
imported_after
string <date-time>
Example: imported_after=2020-01-01T00:00:00.000Z

Include orders imported on or after this date (format ISO 8601 default time zone is America/New_York)

seller_updated_after
string <date-time>
Example: seller_updated_after=2020-01-01T00:00:00.000Z

Include orders updated by the seller on or after this date (format ISO 8601 default time zone is America/New_York)

has_errors
boolean
Example: has_errors=true

Include orders either with or without errors If not set, orders will be returned regardless of the presence/absence of errors

page_size
integer [ 10 .. 50 ]
Default: 20

The number of orders per page to return

cursor
string
Example: cursor=12FDG-31dsfgHW

Cursor for the next page of orders

Responses

Response samples

Content type
application/json
{
  • "orders": [
    ],
  • "next_cursor": "12FDG-31dsfgHW"
}

Get Order

Get a specific order from FeedAMP

Authorizations:
bearerAuth
path Parameters
mp_order_number
required
string

The unique Id for an order that is generated by the marketplace

Responses

Response samples

Content type
application/json
{
  • "mp_order_number": "111-99998888-55555",
  • "sales_channel": "Marketplace.com",
  • "location": {
    },
  • "customer": {
    },
  • "purchase_date": "2018-05-01T23:52:01.000Z",
  • "currency": "USD",
  • "delivery_notes": "leave by the back door.",
  • "earliest_ship_date": "2018-02-04T22:00:00.000Z",
  • "latest_ship_date": "2018-02-07T22:00:00.000Z",
  • "latest_delivery_date": "2018-02-10T22:00:00.000Z",
  • "earliest_delivery_date": "2018-02-10T22:00:00.000Z",
  • "gift_message": "Happy birthday!",
  • "marketing_opt_in": false,
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "order_lines": [
    ],
  • "fulfillments": [
    ],
  • "order_additional_properties": { },
  • "acknowledged": true,
  • "status": "IN_PROGRESS",
  • "marketplace_state": "PENDING",
  • "is_marketplace_fulfilled": true,
  • "fulfillment_type": "shipment",
  • "errors": [
    ]
}

Place Order

Insert an order into or update an existing order in FeedAMP. If updating an order, we only allow specific fields to be updated.

Authorizations:
bearerAuth
path Parameters
mp_order_number
required
string

The unique Id for an order that is generated by the marketplace

Request Body schema: application/json
mp_order_number
required
string [ 1 .. 128 ] characters

The primary order number used to identify the order in the marketplace's system

sales_channel
required
string

The specific channel within a marketplace in which orders are processed (typically corresponds to region)

object (Location)

Details about the location (e.g. store) associated with an order

source_location_id
string

The location identifier assigned by the source platform

client_location_id
string

The location identifier assigned by the client platform

name
string

The assigned name for the location

address
string

The address of the location

required
object (Customer)
full_name
string

The full name of the customer

email
string

The customer's email address

phone
string

The phone number of the customer

vat
string

International Value-Added Tax identification number of customer

purchase_date
required
string <date-time>

The datetime of the purchase date. ISO 8601 date-time YYYY-MM-DDTH:i:sZ (all times must be in UTC)

currency
required
string (ISOCurrencyCodes)
Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYN" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "CNY" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLE" "SLL" "SOS" "SRD" "SSP" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UYW" "UZS" "VED" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"

ISO 4217 Currency codes

delivery_notes
string

The customer's instructions to the delivery service regarding where/how to leave the package.

earliest_ship_date
string <date-time>

The earliest expected ship-by date. ISO 8601 date-time YYYY-MM-DDTH:i:sZ (all times must be in UTC)

latest_ship_date
string <date-time>

The latest expected ship-by date. ISO 8601 date-time YYYY-MM-DDTH:i:sZ (all times must be in UTC)

latest_delivery_date
string <date-time>

The latest expected deliver-by date. ISO 8601 date-time YYYY-MM-DDTH:i:sZ (all times must be in UTC)

earliest_delivery_date
string <date-time>

The earliest expected deliver-by date. ISO 8601 date-time YYYY-MM-DDTH:i:sZ (all times must be in UTC)

gift_message
string

Gift message attached to order

marketing_opt_in
boolean

Whether the customer opted in to marketing emails

required
object (StreetAddress)
full_name
required
string

Name of primary recipient

address_type
string

What kind of establishment is located at this address?

address1
required
string

Street address, line 1

address2
string

Street address, line 2

address3
string

Street address, line 3 (international shipping address info)

city
required
string

Address (City)

state
required
string

Address (State or Province)

postal_code
required
string

Address (Postal or Zip code)

country_code
required
string (ISOCountryCodes)
Enum: "ABW" "AFG" "AGO" "AIA" "ALA" "ALB" "AND" "ARE" "ARG" "ARM" "ASM" "ATA" "ATF" "ATG" "AUS" "AUT" "AZE" "BDI" "BEL" "BEN" "BES" "BFA" "BGD" "BGR" "BHR" "BHS" "BIH" "BLM" "BLR" "BLZ" "BMU" "BOL" "BRA" "BRB" "BRN" "BTN" "BVT" "BWA" "CAF" "CAN" "CCK" "CHE" "CHL" "CHN" "CIV" "CMR" "COD" "COG" "COK" "COL" "COM" "CPV" "CRI" "CUB" "CUW" "CXR" "CYM" "CYP" "CZE" "DEU" "DJI" "DMA" "DNK" "DOM" "DZA" "ECU" "EGY" "ERI" "ESH" "ESP" "EST" "ETH" "FIN" "FJI" "FLK" "FRA" "FRO" "FSM" "GAB" "GBR" "GEO" "GGY" "GHA" "GIB" "GIN" "GLP" "GMB" "GNB" "GNQ" "GRC" "GRD" "GRL" "GTM" "GUF" "GUM" "GUY" "HKG" "HMD" "HND" "HRV" "HTI" "HUN" "IDN" "IMN" "IND" "IOT" "IRL" "IRN" "IRQ" "ISL" "ISR" "ITA" "JAM" "JEY" "JOR" "JPN" "KAZ" "KEN" "KGZ" "KHM" "KIR" "KNA" "KOR" "KWT" "LAO" "LBN" "LBR" "LBY" "LCA" "LIE" "LKA" "LSO" "LTU" "LUX" "LVA" "MAC" "MAF" "MAR" "MCO" "MDA" "MDG" "MDV" "MEX" "MHL" "MKD" "MLI" "MLT" "MMR" "MNE" "MNG" "MNP" "MOZ" "MRT" "MSR" "MTQ" "MUS" "MWI" "MYS" "MYT" "NAM" "NCL" "NER" "NFK" "NGA" "NIC" "NIU" "NLD" "NOR" "NPL" "NRU" "NZL" "OMN" "PAK" "PAN" "PCN" "PER" "PHL" "PLW" "PNG" "POL" "PRI" "PRK" "PRT" "PRY" "PSE" "PYF" "QAT" "REU" "ROU" "RUS" "RWA" "SAU" "SDN" "SEN" "SGP" "SGS" "SHN" "SJM" "SLB" "SLE" "SLV" "SMR" "SOM" "SPM" "SRB" "SSD" "STP" "SUR" "SVK" "SVN" "SWE" "SWZ" "SXM" "SYC" "SYR" "TCA" "TCD" "TGO" "THA" "TJK" "TKL" "TKM" "TLS" "TON" "TTO" "TUN" "TUR" "TUV" "TWN" "TZA" "UGA" "UKR" "UMI" "URY" "USA" "UZB" "VAT" "VCT" "VEN" "VGB" "VIR" "VNM" "VUT" "WLF" "WSM" "YEM" "ZAF" "ZMB" "ZWE"

ISO 3166-1 alpha-3 country codes

phone
string

Phone number associated with address

object (StreetAddress)
full_name
required
string

Name of primary recipient

address_type
string

What kind of establishment is located at this address?

address1
required
string

Street address, line 1

address2
string

Street address, line 2

address3
string

Street address, line 3 (international shipping address info)

city
required
string

Address (City)

state
required
string

Address (State or Province)

postal_code
required
string

Address (Postal or Zip code)

country_code
required
string (ISOCountryCodes)
Enum: "ABW" "AFG" "AGO" "AIA" "ALA" "ALB" "AND" "ARE" "ARG" "ARM" "ASM" "ATA" "ATF" "ATG" "AUS" "AUT" "AZE" "BDI" "BEL" "BEN" "BES" "BFA" "BGD" "BGR" "BHR" "BHS" "BIH" "BLM" "BLR" "BLZ" "BMU" "BOL" "BRA" "BRB" "BRN" "BTN" "BVT" "BWA" "CAF" "CAN" "CCK" "CHE" "CHL" "CHN" "CIV" "CMR" "COD" "COG" "COK" "COL" "COM" "CPV" "CRI" "CUB" "CUW" "CXR" "CYM" "CYP" "CZE" "DEU" "DJI" "DMA" "DNK" "DOM" "DZA" "ECU" "EGY" "ERI" "ESH" "ESP" "EST" "ETH" "FIN" "FJI" "FLK" "FRA" "FRO" "FSM" "GAB" "GBR" "GEO" "GGY" "GHA" "GIB" "GIN" "GLP" "GMB" "GNB" "GNQ" "GRC" "GRD" "GRL" "GTM" "GUF" "GUM" "GUY" "HKG" "HMD" "HND" "HRV" "HTI" "HUN" "IDN" "IMN" "IND" "IOT" "IRL" "IRN" "IRQ" "ISL" "ISR" "ITA" "JAM" "JEY" "JOR" "JPN" "KAZ" "KEN" "KGZ" "KHM" "KIR" "KNA" "KOR" "KWT" "LAO" "LBN" "LBR" "LBY" "LCA" "LIE" "LKA" "LSO" "LTU" "LUX" "LVA" "MAC" "MAF" "MAR" "MCO" "MDA" "MDG" "MDV" "MEX" "MHL" "MKD" "MLI" "MLT" "MMR" "MNE" "MNG" "MNP" "MOZ" "MRT" "MSR" "MTQ" "MUS" "MWI" "MYS" "MYT" "NAM" "NCL" "NER" "NFK" "NGA" "NIC" "NIU" "NLD" "NOR" "NPL" "NRU" "NZL" "OMN" "PAK" "PAN" "PCN" "PER" "PHL" "PLW" "PNG" "POL" "PRI" "PRK" "PRT" "PRY" "PSE" "PYF" "QAT" "REU" "ROU" "RUS" "RWA" "SAU" "SDN" "SEN" "SGP" "SGS" "SHN" "SJM" "SLB" "SLE" "SLV" "SMR" "SOM" "SPM" "SRB" "SSD" "STP" "SUR" "SVK" "SVN" "SWE" "SWZ" "SXM" "SYC" "SYR" "TCA" "TCD" "TGO" "THA" "TJK" "TKL" "TKM" "TLS" "TON" "TTO" "TUN" "TUR" "TUV" "TWN" "TZA" "UGA" "UKR" "UMI" "URY" "USA" "UZB" "VAT" "VCT" "VEN" "VGB" "VIR" "VNM" "VUT" "WLF" "WSM" "YEM" "ZAF" "ZMB" "ZWE"

ISO 3166-1 alpha-3 country codes

phone
string

Phone number associated with address

required
Array of objects (OrderLine) non-empty

A collection of OrderLine objects. This property contains the individual order lines that the seller is to fulfill

Array (non-empty)
mp_line_number
required
string

The marketplace identifier of this unique order line

sku
required
string

The SKU of the marketplace product represented by this order line

product_name
required
string

The product title, as displayed in the marketplace listing

quantity
required
integer >= 1

The amount of product ordered

unit_price
required
number >= 0

The price for a single (1) quantity of product (not including tax, shipping, or discounts)

shipping_method
string

The shipping method the seller is required to use to fulfill this order line

shipping_price
number >= 0

The total shipping price for this order line

Array of objects (Tax) >= 0 items

A collection of taxes that are levied against the order line

Array (>= 0 items)
type
required
string
Enum: "SHIPPING" "SALES" "GST" "PST" "VAT"

The type of tax

amount
required
number >= 0

The tax amount

Array of objects (Discount) >= 0 items

A collection of discounts that are applied to the order line

Array (>= 0 items)
name
required
string

The discount identifier, as configured in the marketplace

amount
required
number >= 0

The order line total discount amount

type
required
string
Enum: "ITEM" "SHIPPING"

The type of discount

  • ITEM - Discount applies to item price
  • SHIPPING - Discount applies to shipping price
is_tax_collected_by_marketplace
boolean

Indicates whether taxes are collected by the marketplace

object

Key/Value pairs of data the marketplace wants to associate with an order line

property name*
additional property
any
object

Key/Value pairs of data the marketplace wants to associate with an order

property name*
additional property
any
marketplace_state
required
string
Enum: "PENDING" "AWAITING_SHIPMENT" "SHIPPED" "CANCELLED"

The state of the order in the marketplace

  • PENDING - Order is still awaiting payment or other finalization before being eligible for fulfillment
  • AWAITING_SHIPMENT - The marketplace does not yet have any fulfillment information for the order
  • SHIPPED - The marketplace has successfully retrieved fulfillment information for the entire order
  • CANCELLED - The order has been cancelled, either due to action initiated by the marketplace (customer cancelled) or the entire order has been cancelled during fulfillment processing (seller cancelled)
is_marketplace_fulfilled
boolean
Default: false

Whether the order is fulfilled by the marketplace, and no further action is required by the seller to fulfill

  • True - The order is fulfilled by the marketplace
  • False - The seller must fulfill the order
fulfillment_type
string (FulfillmentType)
Enum: "shipment" "digital" "pickup"

Type of fulfillment required for the order

  • shipment - Requires shipment by the seller
  • digital - No physical fulfillment
  • pickup - Order prepared for local pickup by buyer

Responses

Request samples

Content type
application/json
{
  • "mp_order_number": "111-99998888-55555",
  • "sales_channel": "Marketplace.com",
  • "location": {
    },
  • "customer": {
    },
  • "purchase_date": "2018-05-01T23:52:01.000Z",
  • "currency": "USD",
  • "delivery_notes": "leave by the back door.",
  • "earliest_ship_date": "2018-02-04T22:00:00.000Z",
  • "latest_ship_date": "2018-02-07T22:00:00.000Z",
  • "latest_delivery_date": "2018-02-10T22:00:00.000Z",
  • "earliest_delivery_date": "2018-02-10T22:00:00.000Z",
  • "gift_message": "Happy birthday!",
  • "marketing_opt_in": false,
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "order_lines": [
    ],
  • "order_additional_properties": { },
  • "marketplace_state": "PENDING",
  • "is_marketplace_fulfilled": false,
  • "fulfillment_type": "shipment"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Fulfillments

Get the seller-supplied fulfillment information for all order lines in an order

Authorizations:
bearerAuth
path Parameters
mp_order_number
required
string

The unique Id for an order that is generated by the marketplace

Responses

Response samples

Content type
application/json
{
  • "status": "PENDING",
  • "is_marketplace_fulfilled": true,
  • "fulfillments": [
    ]
}

Report Errors

This endpoint allows the marketplace to report any errors that occur while processing a fulfillment/cancellation for an order line

Authorizations:
bearerAuth
path Parameters
mp_order_number
required
string

The unique Id for an order that is generated by the marketplace

Request Body schema: application/json
Array
mp_line_number
string <= 128 characters

Order line number that has an error

code
required
string
Enum: "EXCESS_FULFILLMENT" "EXCESS_CANCELLATION" "INVALID_TRACKING_NUMBER" "INVALID_TRACKING_URL" "INVALID_CARRIER" "INVALID_SHIPPING_DATE" "INVALID_CANCEL_REASON" "ORDER_FULFILLED" "ORDER_CANCELLED" "ORDER_REFUNDED"

Code to uniquely identify the type of error

message
required
string

The error message for the error code

Array of objects (ErrorDebug)
Array
property name*
additional property
any

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]