logo
API docs by Redocly

FeedAMP Order Management API (1.1.17)

The Order Management API allows you to automate order fulfillment, giving you more control and efficiency over your order management. Use it to access and review order data, streamline fulfillment, and handle returns and refunds.

What You'll Learn:

  • How to authenticate and manage API access.
  • Retrieving and confirming order information.
  • Updating order information fulfillment statuses.
  • Processing returns and refunds.

FeedAMP Process

  • FeedAMP frequently imports new orders from a Seller's marketplace accounts for new orders. A Seller can fetch their orders using this FeedAMP Rest API.
  • Seller then confirms order receipt to FeedAMP for each order.
  • After fully shipping and/or cancelling all items, Seller will update the fulfillment information in for the order in FeedAMP. FeedAMP will then forward this information to that order's marketplace account.
  • After fulfillment, a Seller may issue a refund to an order marketplace, by posting a refund to it on FeedAMP.

Authentication

FeedAMP Always enforces IP Whitelisting. The request must come from a white listed ip.

  • FeedAMP uses HTTP Basic Authentication to generate an auth token.
  • The token is used along with a client id in every request until the token expires.
  • When the token expires, generate a new token
  • Requests that fail authentication will receive a 401 error. Forbidden requests due to unauthorized client id wil received a 403 error.

Note

Future additional fields may be added to the order_info field over time as we actively develop the FeedAMP product. It is expected that Rest API integrations are able to tolerate additive (i.e. non-breaking) updates without requiring advance notice. Feedonomics will still continue to send out communication informing integrators of such updates after the fact.

Authentication

Get an authentication token.

Use your username/password and HTTP Basic Authentication to get an authentication token Use the token along with your client id in all subsequent requests. When the token expires make another request to this route and get a new token.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
{
  • "token": "53bf15c-this-is-an-example-token-b7769e17d-example-3f82af26f-example-12588b14d-example-15426324a-example-a5b2f721c-example-26fc7"
}

Orders

Get new orders

Get all orders that have not yet been confirmed by the seller. The maximum recommended call frequency for retrieving data from this endpoint is 2 requests per second.

Authorizations:
BasicAuth
query Parameters
include_raw
boolean
Default: false

Set true to include the raw data from the marketplace for each order in results.

limit
number

The max number of orders in the response (50-200). Default is 100.

cursor
string

Cursor for the next page of orders.

marketplace_fulfilled
boolean

Set true to only include with marketplace_fulfilled set

header Parameters
token
required
string

The Authentication token obtained from the get_token route.

client
required
integer

The id of the client making the request.

Responses

Response samples

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

Get order by {order-id}

Get an order by order-id.

Authorizations:
BasicAuth
path Parameters
order-id
required
integer

The id of the order.

query Parameters
include_raw
boolean
Default: false

Set true to include the raw data from the marketplace for each order in results.

header Parameters
token
required
string

The Authentication token obtained from the get_token route.

client
required
integer

The id of the client making the request.

Responses

Response samples

Content type
application/json
{
  • "order": [
    ]
}

Confirm an order

Confirm receipt of the order in FeedAMP. FeedAMP will acknowledge the order in the marketplace depending on the marketplace/seller settings.

Authorizations:
BasicAuth
path Parameters
order-id
required
string

FeedAMP order id

header Parameters
token
required
string

The Authentication token obtained from the get_token route.

client
required
integer

The id of the client making the request.

Request Body schema: */*
optional

Confirmation details

cp_order_number
required
string

Seller order number. Must be unqiue for each order.

Responses

Response samples

Content type
application/json
{
  • "order": {
    }
}

Fulfill an order

Fulfill or cancel order. Post all fulfillments together to the Rest API for the order to move to fulfilled state. As a PUT request, the fulfillment call fully replaces all fulfillments currently stored in FeedAMP for the particular order. New fulfillments may be added to prior ones by retrieving the fufillments via a GET request, and then calling the PUT /fulfill endpoint with the new fulfillments added. Once all items have been fulfilled, the order will change state and no longer accept further updates.

If the order contains cancellations:

  • Cancellation Reasons must be one of the following reasons: [customer_cancelled, unable_to_ship, out_of_stock, price_error, tax_error, shipping_price_error, other].
  • Please be aware that the use of 'other' is not recommended - some marketplaces may not accept it.
Authorizations:
BasicAuth
path Parameters
order-id
required
string

FeedAMP order id.

header Parameters
token
required
string

The Authentication token obtained from the get_token route.

client
required
integer

The id of the client making the request.

Request Body schema: */*
optional
invoice_number
string

An optional billing invoice number generated by your ecommerce platform. Currently only required for SkyHub marketplace.

required
Array of objects

List of ordered products.

Array
mp_line_number
required
string

The order line identifier provided by the marketplace.

sku
string

The SKU of the order line.

Array of objects

Array of fulfillment objects or null

Array
quantity_shipped
required
integer

The quantity of items (of this order line) in the shipment.

shipped_date
required
string <date-time>

The date-time when the shipment was sent out (time is optional). ISO 8601 format required.

carrier
required
string

The shipment's service carrier company name.

tracking_number
required
string

The shipment's tracking number.

tracking_url
string

The shipment's tracking URL. Note: This field is required by some marketplaces if the carrier is not recognized.

Array of objects

Array of cancellation objects or null

Array
quantity_cancelled
required
integer

The quantity of items in the order line being cancelled.

cancellation_reason
required
string
Enum: "customer_cancelled" "unable_to_ship" "out_of_stock" "price_error" "tax_error" "shipping_price_error" "other"

The reason for the cancellation. Use of 'other' is not recommended - some marketplaces may not accept it.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Seller-Initiated Refunds

Create a refund

Create a refund in FeedAMP, FeedAMP will communicate the refund to the marketplace. A single refund can only be applied to one order line. A seller that wishes to refund more than one order line in an order must make multiple refunds in FeedAMP.

Authorizations:
BasicAuth
path Parameters
order-id
required
string

FeedAMP order id

header Parameters
token
required
string

The Authentication token obtained from the get_token route.

client
required
integer

The id of the client making the request.

Request Body schema: */*
optional
required
object
cp_refund_number
required
string

Seller Refund ID. Must be unique for all posted refunds.

mp_line_number
required
string

The marketplace's order line identifier

refund_reason
required
string
Enum: "customer_cancelled" "customer_return" "accidental_order" "wrong_item_received" "defective_item_received" "damaged_item_received" "item_never_received" "item_received_late" "wrong_quantity_received" "could_not_ship" "abandoned" "price_error" "tax_error" "shipping_cost_error" "other"

The reason for the refund. Please see Enum for accepted values. Use of 'other' is not recommended - some marketplaces may not accept it. If set to 'other', it is strongly recommended to enter a description in the 'refund_notes' field.

currency
required
string

The currency in ISO 4217 format.

refund_quantity
integer

The quantity that is being refunded for the order line.

item_refund
number

The amount being refunded for the item price.

item_tax_refund
number

The amount being refunded for the item sales tax.

shipping_refund
number

The amount being refunded for the shipping cost.

shipping_tax_refund
number

The amount being refunded for the shipping tax

discount_refund
number

The discount amount being refunded/undone.

refund_notes
string

Custom notes on the refund to send to the customer (if supported by the marketplace). If refund_reason is set to 'other', it is recommended to populate this field.

Responses

Response samples

Content type
application/json
{
  • "id": "123",
  • "order_id": "1234",
  • "state": "CREATED",
  • "refund_info": {
    }
}

Customer-Initiated Returns

Search returns

Search returns for a client. Filter results via query params. The maximum recommended call frequency for retrieving data from this endpoint is 2 requests per second.

Authorizations:
BasicAuth
query Parameters
open
boolean

Setting to true will limit results to Returns considered to be in an open state. Setting to false will produce closed state Returns. Open Returns are Returns that are NOT in a terminal state. Terminal states are considered to be Merchant Refunded, Merchant Rejected, or Customer Cancelled.

NOTE: This parameter is overridden by the "state" parameter if provided

state
Array of strings non-empty
Items Enum: "Pending Authorization" "Pending Confirmation" "Pending Shipping" "Pending Refund" "Processing Refund" "Merchant Refunded" "Merchant Rejected" "Customer Cancelled"
Examples:
  • state=Pending Authorization,Pending Confirmation,Pending Shipping,Pending Refund,Processing Refund - Get all open returns
  • state=Merchant Refunded,Merchant Rejected,Customer Cancelled - Get all closed returns
  • state=Customer Cancelled - Get customer cancelled returns

Comma delimited list of Return states to filter by. e.g: ?state=Pending Authorization,Pending Confirmation

marketplaces
string

comma delimited list of marketplace IDs to filter results by

created-before
string <date-time>

filter results by returns created before date-time (ISO 8601) | if timezone is not specified default is EST/EDT.

created-after
string <date-time>

filter results by returns created after date-time (ISO 8601) | if timezone is not specified default is EST/EDT.

refreshed-before
string <date-time>

filter results by returns refreshed before date-time (ISO 8601) | if timezone is not specified default is EST/EDT.

refreshed-after
string <date-time>

filter results by returns refreshed after date-time (ISO 8601) | if timezone is not specified default is EST/EDT.

merchant-return-number
string

filter results by merchant return number (RMA)

limit
number

THe max number of returns in the response (50-200). Default is 100.

cursor
string

Cursor for the next page of returns.

header Parameters
token
required
string

The Authentication token obtained from the get_token route.

client
required
integer

The id of the client making the request.

Responses

Response samples

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

Get a single return resource

Get a return by return ID

Authorizations:
BasicAuth
path Parameters
return-id
required
integer

The id of the return.

header Parameters
token
required
string

The Authentication token obtained from the get_token route.

client
required
integer

The id of the client making the request.

Responses

Response samples

Content type
application/json
{
  • "return": {
    }
}

Authorize a return

Authorize (or reject) a customer-initated return. This only applies to returns in the Pending Authorization state. This is also an opportunity for the seller to supply their own return number (i.e RMA) or shipping label.

Authorizations:
BasicAuth
path Parameters
return-id
required
string

FeedAMP return id

header Parameters
token
required
string

The Authentication token obtained from the get_token route.

client
required
integer

The id of the client making the request.

Request Body schema: */*
optional

Return Authorization data

merchant_return_number
required
string

Seller Return Number, or RMA. Field is required, but can also be set to the mp_return_number value if desired. This number must be unique across all returns.

Responses

Response samples

Content type
application/json
{
  • "return": {
    }
}

Issue refund to customer for return

Issue a full refund to the customer and close out the return. It's recommended to issue a refund on a return when it's in the Pending Refund state.

Authorizations:
BasicAuth
path Parameters
return-id
required
string

FeedAMP return id.

header Parameters
token
required
string

The Authentication token obtained from the get_token route.

client
required
integer

The id of the client making the request.

Request Body schema: application/json

Authorize Refund Amounts Payload

required
Array of RefundFullAmount (object) or RefundPartialAmount (object)

Refund Lines to be refunded

Array
One of
feedamp_return_line_id
required
string

The refund line number to be refunded

merchant_full_refund
required
boolean

Indicates that all applicaple principle and shipping are to be refunded (only true is allowed)

Responses

Request samples

Content type
application/json
{
  • "merchant_refund_lines": [
    ]
}

Response samples

Content type
application/json
{
  • "return": {
    }
}