The API allows marketplaces to:
/orders/{mp_order_number}
endpoint./orders
endpoint.
/orders/{mp_order_number}
or GET /orders/{mp_order_number}/fulfillments
endpoint./orders/{mp_order_number}/errors
endpoint./orders/{mp_order_number}
endpoint.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.
Start of Oauth process a Seller's to authorize access to a marketplace in Feedamp.
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 |
Get a new access token for a specific seller using a one-time authorization code or a valid refresh token
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 |
{- "grant_type": "refresh_token",
- "code": "string",
- "refresh_token": "string",
- "client_id": "string",
- "client_secret": "string"
}
{- "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwibmFtZSI6IkZlZWRhbXAiLCJpYXQiOjF9._p278gl45T7hITPuson9KEiE-SMYwms3q-2DbAgiev8",
- "token_type": "Bearer",
- "refresh_token": "CLIENT_REFRESH_TOKEN",
- "expires_in": 3600
}
Get all orders from FeedAMP for a seller, filtered by the provided query params
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
|
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 |
{- "orders": [
- {
- "mp_order_number": "111-99998888-55555",
- "sales_channel": "Marketplace.com",
- "location": {
- "source_location_id": "a0b0c0-f-f-f-f00f",
- "client_location_id": "my-locid_00",
- "name": "City Store - Citiesville",
- "address": "1234 Street Ave., City Township, NJ 00000-0000"
}, - "customer": {
- "full_name": "A. Customer",
- "email": "customer@internet-provider.com",
- "phone": "5558675309",
- "vat": "78131452263"
}, - "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": {
- "full_name": "John M. Doe",
- "address_type": "business",
- "address1": "123 Fake Street",
- "address2": "Building 456",
- "address3": "Room 789",
- "city": "Ghost Town",
- "state": "DC",
- "postal_code": "91234",
- "country_code": "USA",
- "phone": "9997776666"
}, - "billing_address": {
- "full_name": "John M. Doe",
- "address_type": "business",
- "address1": "123 Fake Street",
- "address2": "Building 456",
- "address3": "Room 789",
- "city": "Ghost Town",
- "state": "DC",
- "postal_code": "91234",
- "country_code": "USA",
- "phone": "9997776666"
}, - "order_lines": [
- {
- "mp_line_number": "XX-111-FF-1111",
- "sku": "1234-12353",
- "product_name": "ACME Super Product",
- "quantity": 1,
- "unit_price": 200,
- "shipping_method": "Standard",
- "shipping_price": 1.95,
- "taxes": [
- {
- "type": "SHIPPING",
- "amount": 0
}
], - "discounts": [
- {
- "name": "Spring Discount",
- "amount": 0,
- "type": "ITEM"
}
], - "is_tax_collected_by_marketplace": false,
- "order_line_additional_properties": { }
}
], - "order_additional_properties": { },
- "marketplace_state": "PENDING",
- "is_marketplace_fulfilled": false,
- "fulfillment_type": "shipment"
}
], - "next_cursor": "12FDG-31dsfgHW"
}
Get a specific order from FeedAMP
mp_order_number required | string The unique Id for an order that is generated by the marketplace |
{- "mp_order_number": "111-99998888-55555",
- "sales_channel": "Marketplace.com",
- "location": {
- "source_location_id": "a0b0c0-f-f-f-f00f",
- "client_location_id": "my-locid_00",
- "name": "City Store - Citiesville",
- "address": "1234 Street Ave., City Township, NJ 00000-0000"
}, - "customer": {
- "full_name": "A. Customer",
- "email": "customer@internet-provider.com",
- "phone": "5558675309",
- "vat": "78131452263"
}, - "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": {
- "full_name": "John M. Doe",
- "address_type": "business",
- "address1": "123 Fake Street",
- "address2": "Building 456",
- "address3": "Room 789",
- "city": "Ghost Town",
- "state": "DC",
- "postal_code": "91234",
- "country_code": "USA",
- "phone": "9997776666"
}, - "billing_address": {
- "full_name": "John M. Doe",
- "address_type": "business",
- "address1": "123 Fake Street",
- "address2": "Building 456",
- "address3": "Room 789",
- "city": "Ghost Town",
- "state": "DC",
- "postal_code": "91234",
- "country_code": "USA",
- "phone": "9997776666"
}, - "order_lines": [
- {
- "mp_line_number": "XX-111-FF-1111",
- "sku": "1234-12353",
- "product_name": "ACME Super Product",
- "quantity": 1,
- "unit_price": 200,
- "shipping_method": "Standard",
- "shipping_price": 1.95,
- "taxes": [
- {
- "type": "SHIPPING",
- "amount": 0
}
], - "discounts": [
- {
- "name": "Spring Discount",
- "amount": 0,
- "type": "ITEM"
}
], - "is_tax_collected_by_marketplace": false,
- "order_line_additional_properties": { }
}
], - "fulfillments": [
- {
- "mp_line_number": "XX-111-FF-1111",
- "shipments": [
- {
- "quantity": 1,
- "shipped_date": "2023-05-02",
- "carrier": "UPS",
- "tracking_number": "XXX-DDD-XXXX-DDDD",
}
], - "cancellations": [
- {
- "quantity": 1,
- "reason": "customer_cancelled"
}
], - "pending": {
- "quantity": 0
}, - "status": "PENDING"
}
], - "order_additional_properties": { },
- "acknowledged": true,
- "status": "IN_PROGRESS",
- "marketplace_state": "PENDING",
- "is_marketplace_fulfilled": true,
- "fulfillment_type": "shipment",
- "errors": [
- {
- "mp_line_number": "XX-123-YY-1234",
- "code": "INVALID_TRACKING_NUMBER",
- "message": "Value SOMETHING not valid for state",
- "debug": [
- { }
]
}
]
}
Insert an order into or update an existing order in FeedAMP. If updating an order, we only allow specific fields to be updated.
mp_order_number required | string The unique Id for an order that is generated by the marketplace |
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 | |||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
required | object (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) | ||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
object (StreetAddress) | |||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
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)
| |||||||||||||||||||||||||||||||||||||||||
object Key/Value pairs of data the marketplace wants to associate with an order | |||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
marketplace_state required | string Enum: "PENDING" "AWAITING_SHIPMENT" "SHIPPED" "CANCELLED" The state of the order in the marketplace
| ||||||||||||||||||||||||||||||||||||||||
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
| ||||||||||||||||||||||||||||||||||||||||
fulfillment_type | string (FulfillmentType) Enum: "shipment" "digital" "pickup" Type of fulfillment required for the order
|
{- "mp_order_number": "111-99998888-55555",
- "sales_channel": "Marketplace.com",
- "location": {
- "source_location_id": "a0b0c0-f-f-f-f00f",
- "client_location_id": "my-locid_00",
- "name": "City Store - Citiesville",
- "address": "1234 Street Ave., City Township, NJ 00000-0000"
}, - "customer": {
- "full_name": "A. Customer",
- "email": "customer@internet-provider.com",
- "phone": "5558675309",
- "vat": "78131452263"
}, - "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": {
- "full_name": "John M. Doe",
- "address_type": "business",
- "address1": "123 Fake Street",
- "address2": "Building 456",
- "address3": "Room 789",
- "city": "Ghost Town",
- "state": "DC",
- "postal_code": "91234",
- "country_code": "USA",
- "phone": "9997776666"
}, - "billing_address": {
- "full_name": "John M. Doe",
- "address_type": "business",
- "address1": "123 Fake Street",
- "address2": "Building 456",
- "address3": "Room 789",
- "city": "Ghost Town",
- "state": "DC",
- "postal_code": "91234",
- "country_code": "USA",
- "phone": "9997776666"
}, - "order_lines": [
- {
- "mp_line_number": "XX-111-FF-1111",
- "sku": "1234-12353",
- "product_name": "ACME Super Product",
- "quantity": 1,
- "unit_price": 200,
- "shipping_method": "Standard",
- "shipping_price": 1.95,
- "taxes": [
- {
- "type": "SHIPPING",
- "amount": 0
}
], - "discounts": [
- {
- "name": "Spring Discount",
- "amount": 0,
- "type": "ITEM"
}
], - "is_tax_collected_by_marketplace": false,
- "order_line_additional_properties": { }
}
], - "order_additional_properties": { },
- "marketplace_state": "PENDING",
- "is_marketplace_fulfilled": false,
- "fulfillment_type": "shipment"
}
[- {
- "code": "FEEDAMP_FIELD_INVALID_VALUE",
- "message": "Value SOMETHING not valid for state"
}
]
Get the seller-supplied fulfillment information for all order lines in an order
mp_order_number required | string The unique Id for an order that is generated by the marketplace |
{- "status": "PENDING",
- "is_marketplace_fulfilled": true,
- "fulfillments": [
- {
- "mp_line_number": "XX-111-FF-1111",
- "shipments": [
- {
- "quantity": 1,
- "shipped_date": "2023-05-02",
- "carrier": "UPS",
- "tracking_number": "XXX-DDD-XXXX-DDDD",
}
], - "cancellations": [
- {
- "quantity": 1,
- "reason": "customer_cancelled"
}
], - "pending": {
- "quantity": 0
}, - "status": "PENDING"
}
]
}
This endpoint allows the marketplace to report any errors that occur while processing a fulfillment/cancellation for an order line
mp_order_number required | string The unique Id for an order that is generated by the marketplace |
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
|
[- {
- "mp_line_number": "XX-123-YY-1234",
- "code": "INVALID_TRACKING_NUMBER",
- "message": "Value SOMETHING not valid for state",
- "debug": [
- { }
]
}
]
[- {
- "code": "INVALID_STATUS",
- "message": "The status value OTHER is not a valid expected: [SHIPPING, SHIPPED, CANCELLED]",
- "debug": [
- { }
]
}
]