Retrieve Orders

If you're looking to integrate Reverb Orders with your existing eCommerce, inventory, or financial system, you can pull down orders from the Reverb API and make equivalent entries for bookkeeping in your application.

Please also keep the link below bookmarked, as this will be where any pertinent API updates/changes will be made public:

https://www.reverb-api.com/docs/changelog

Fetching Orders Periodically

With this approach, your app pulls orders from Reverb on a timer. You can set up a cron job to do this nightly, or run a manual script to do so.

You can sync orders from Reverb to your application by pulling orders in various ways. The most common one is based on a date range. Note that the dates are in ISO8601 format.

curl -XGET 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/orders/selling/all?updated_start_date=2015-01-01T12:00-00:00&updated_end_date=2015-01-02T12:00-00:00

The response will contain a list of order objects, which you can parse to update orders in your system.

{
    "total": 2,
    "current_page": 1,
    "total_pages": 1,
    "orders": [
        {
            "amount_product": {
                "amount": "95.00",
                "amount_cents": 9500,
                "currency": "USD",
                "symbol": "$",
                "display": "$95"
            },
            "amount_product_subtotal": {
                "amount": "95.00",
                "amount_cents": 9500,
                "currency": "USD",
                "symbol": "$",
                "display": "$95"
            },
            "shipping": {
                "amount": "8.00",
                "amount_cents": 800,
                "currency": "USD",
                "symbol": "$",
                "display": "$8"
            },
            "amount_tax": {
                "amount": "0.00",
                "amount_cents": 0,
                "currency": "USD",
                "symbol": "$",
                "display": "FREE"
            },
            "total": {
                "amount": "103.00",
                "amount_cents": 10300,
                "currency": "USD",
                "symbol": "$",
                "display": "$103"
            },
            "buyer_name": "Some Buyer",
            "buyer_first_name": "Some",
            "buyer_last_name": "Buyer",
            "buyer_id": 1,
            "created_at": "2017-11-08T18:38:29-05:00",
            "order_number": "2",
            "needs_feedback_for_buyer": false,
            "needs_feedback_for_seller": false,
            "order_type": "instant",
            "paid_at": "2017-11-08T18:38:31-05:00",
            "quantity": 1,
            "shipping_address": {
                "region": "IL",
                "locality": "Chicago",
                "country_code": "US",
                "display_location": "Chicago, IL, United States",
                "id": "2",
                "primary": false,
                "name": "Some Buyer",
                "street_address": "140 Main Street",
                "extended_address": null,
                "postal_code": "62025",
                "phone": "1234567890",
                "unformatted_phone": "1234567890",
                "complete_shipping_address": true,
                "_links": {
                    "self": {
                        "href": "https://reverb.com/api/my/addresses/2"
                    }
                }
            },
            "shipping_date": "2017-11-09",
            "shipped_at": "2017-11-09T15:33:26-05:00",
            "shipping_provider": "USPS",
            "shipping_code": "1234567890",
            "shipping_method": "shipped",
            "local_pickup": false,
            "shop_name": "The Shop",
            "status": "shipped",
            "title": "EarthQuaker Devices Organizer",
            "updated_at": "2017-11-15T19:18:27-05:00",
            "payment_method": "direct_checkout",
            "order_bundle_id": "3",
            "product_id": "2",
            "photos": [
                {
                    "_links": {
                        "large_crop": {
                            "href": "https://images.reverb.com/image/upload/s--GrDd9urH--/c_crop,h_0.750,w_1.000,x_0.000,y_0.168/a_exif,c_thumb,f_auto,fl_progressive,g_south,h_640,q_auto:eco,w_640/v1509557840/dgoa1azwcug29sp5kydj.jpg"
                        },
                        "small_crop": {
                            "href": "https://images.reverb.com/image/upload/s--oj25k2nN--/c_crop,h_0.750,w_1.000,x_0.000,y_0.168/a_exif,c_thumb,f_auto,fl_progressive,g_south,h_296,q_auto:eco,w_296/v1509557840/dgoa1azwcug29sp5kydj.jpg"
                        },
                        "full": {
                            "href": "https://images.reverb.com/image/upload/s--rZAcmKdS--/c_crop,h_0.750,w_1.000,x_0.000,y_0.168/a_exif,c_limit,f_auto,fl_progressive,g_south,h_1136,q_auto:eco,w_640/v1509557840/dgoa1azwcug29sp5kydj.jpg"
                        },
                        "thumbnail": {
                            "href": "https://images.reverb.com/image/upload/s--_1ydOivz--/c_crop,h_0.750,w_1.000,x_0.000,y_0.168/a_exif,c_thumb,f_auto,fl_progressive,g_south,h_192,q_auto:eco,w_192/v1509557840/dgoa1azwcug29sp5kydj.jpg"
                        }
                    }
                }
            ],
            "selling_fee": {
                "amount": "3.61",
                "amount_cents": 361,
                "currency": "USD",
                "symbol": "$",
                "display": "$3.61"
            },
            "shipping_label_fee": {
                "amount": "11.88",
                "amount_cents": 1188,
                "currency": "USD",
                "symbol": "$",
                "display": "$11.88"
            },
            "direct_checkout_fee": {
                "amount": "3.03",
                "amount_cents": 303,
                "currency": "USD",
                "symbol": "$",
                "display": "$3.03"
            },
          "tax_on_fees": {            # This property is only applicable to select users. More information for qualifying sellers: https://help.reverb.com/hc/en-us/articles/15478400563603 
                "amount": "0.00",
                "amount_cents": 0,
                "currency": "USD",
                "symbol": "$",
                "display": "$0.00"
            },
            "tax_responsible_party": "reverb", # Alternative value = "seller". Indicates whether tax was remitted by Reverb or not.    
            "direct_checkout_payout": {
                "amount": "84.48",
                "amount_cents": 8448,
                "currency": "USD",
                "symbol": "$",
                "display": "$84.48"
            },
            "_links": {
                "photo": {
                    "href": "https://images.reverb.com/image/upload/s--_1ydOivz--/c_crop,h_0.750,w_1.000,x_0.000,y_0.168/a_exif,c_thumb,f_auto,fl_progressive,g_south,h_192,q_auto:eco,w_192/v1509557840/dgoa1azwcug29sp5kydj.jpg"
                },
                "feedback_for_buyer": {
                    "href": "https://reverb.com/api/orders/2/feedback/buyer"
                },
                "feedback_for_seller": {
                    "href": "https://reverb.com/api/orders/2/feedback/seller"
                },
                "listing": {
                    "href": "https://reverb.com/api/listings/3"
                },
                "start_conversation": {
                    "href": "https://reverb.com/api/my/conversations?listing_id=2&recipient_id=1"
                },
                "web_tracking": {
                    "href": "https://tools.usps.com/go/TrackConfirmAction?qtc_tLabels1=1234567890"
                },
                "web": {
                    "href": "https://reverb.com/my/selling/orders/2"
                },
                "web_listing": {
                    "href": "https://reverb.com/item/2-earthquaker-devices-organizer"
                },
                "self": {
                    "href": "https://reverb.com/api/my/orders/selling/2"
                },
                "mark_picked_up": {
                    "href": "https://reverb.com/api/my/orders/selling/2/mark_picked_up"
                },
                "payments": {
                    "href": "https://reverb.com/api/my/payments/selling?order_id=2"
                },
                "contact_buyer": {
                    "web": {
                        "href": "https://reverb.com/my/messages/new?item=2-earthquaker-devices-organizer&to=3&token=4448b5af4d33d3d7ec7831310609a27e8315320642399c897c506216284f8426"
                    }
                }
            }
        },
        {
            "amount_product": {
                "amount": "75.00",
                "amount_cents": 7500,
                "currency": "USD",
                "symbol": "$",
                "display": "$75"
            },
            "amount_product_subtotal": {
                "amount": "75.00",
                "amount_cents": 7500,
                "currency": "USD",
                "symbol": "$",
                "display": "$75"
            },
            "shipping": {
                "amount": "8.00",
                "amount_cents": 800,
                "currency": "USD",
                "symbol": "$",
                "display": "$8"
            },
            "amount_tax": {
                "amount": "0.00",
                "amount_cents": 0,
                "currency": "USD",
                "symbol": "$",
                "display": "FREE"
            },
            "total": {
                "amount": "83.00",
                "amount_cents": 8300,
                "currency": "USD",
                "symbol": "$",
                "display": "$83"
            },
            "buyer_name": "Another Buyer",
            "buyer_first_name": "Another",
            "buyer_last_name": "Buyer",
            "buyer_id": 10,
            "created_at": "2017-09-25T13:02:06-04:00",
            "order_number": "20",
            "needs_feedback_for_buyer": false,
            "needs_feedback_for_seller": false,
            "order_type": "instant",
            "paid_at": "2017-09-25T13:02:08-04:00",
            "quantity": 1,
            "shipping_address": {
                "region": "PA",
                "locality": "Shiremanstown",
                "country_code": "US",
                "display_location": "Shiremanstown, PA, United States",
                "id": "100",
                "primary": false,
                "name": "Another Buyer",
                "street_address": "102 S Tree Ave",
                "extended_address": "",
                "postal_code": "17011",
                "phone": "1234567890",
                "unformatted_phone": "1234567890",
                "complete_shipping_address": true,
                "_links": {
                    "self": {
                        "href": "https://reverb.com/api/my/addresses/100"
                    }
                }
            },
            "shipping_date": "2017-09-25",
            "shipped_at": "2017-09-25T14:11:25-04:00",
            "shipping_provider": "USPS",
            "shipping_code": "9410836897846174803004",
            "shipping_method": "shipped",
            "local_pickup": false,
            "shop_name": "The Shop",
            "status": "shipped",
            "title": "Fulltone Full-Drive 2 Mosfet",
            "updated_at": "2017-11-11T00:00:09-05:00",
            "payment_method": "direct_checkout",
            "order_bundle_id": "20",
            "product_id": "20",
            "photos": [
                {
                    "_links": {
                        "large_crop": {
                            "href": "https://images.reverb.com/image/upload/s--Hgd6G0SR--/a_exif,c_thumb,f_auto,fl_progressive,g_south,h_640,q_auto:eco,w_640/v1505938525/zhjqjurkiuqos1tcorir.jpg"
                        },
                        "small_crop": {
                            "href": "https://images.reverb.com/image/upload/s--VIXw5qEa--/a_exif,c_thumb,f_auto,fl_progressive,g_south,h_296,q_auto:eco,w_296/v1505938525/zhjqjurkiuqos1tcorir.jpg"
                        },
                        "full": {
                            "href": "https://images.reverb.com/image/upload/s--ml3WTIaI--/a_exif,c_limit,f_auto,fl_progressive,g_south,h_1136,q_auto:eco,w_640/v1505938525/zhjqjurkiuqos1tcorir.jpg"
                        },
                        "thumbnail": {
                            "href": "https://images.reverb.com/image/upload/s--8vQsJRb9--/a_exif,c_thumb,f_auto,fl_progressive,g_south,h_192,q_auto:eco,w_192/v1505938525/zhjqjurkiuqos1tcorir.jpg"
                        }
                    }
                }
            ],
            "sku": "rev-20",
            "selling_fee": {
                "amount": "2.91",
                "amount_cents": 291,
                "currency": "USD",
                "symbol": "$",
                "display": "$2.91"
            },
            "shipping_label_fee": {
                "amount": "9.75",
                "amount_cents": 975,
                "currency": "USD",
                "symbol": "$",
                "display": "$9.75"
            },
          	"affirm_promotion_fee": {             
                "amount": "0.00",
                "amount_cents": 0,
                "currency": "USD",
                "symbol": "$",
                "display": "$0.00"
            },
            "direct_checkout_fee": {
                "amount": "2.49",
                "amount_cents": 249,
                "currency": "USD",
                "symbol": "$",
                "display": "$2.49"
            },
            "tax_on_fees": {             
                "amount": "0.00",
                "amount_cents": 0,
                "currency": "USD",
                "symbol": "$",
                "display": "$0.00"
            },
            "tax_responsible_party": "reverb",    
            "direct_checkout_payout": {
                "amount": "67.85",
                "amount_cents": 6785,
                "currency": "USD",
                "symbol": "$",
                "display": "$67.85"
            },
            "_links": {
                "photo": {
                    "href": "https://images.reverb.com/image/upload/s--8vQsJRb9--/a_exif,c_thumb,f_auto,fl_progressive,g_south,h_192,q_auto:eco,w_192/v1505938525/zhjqjurkiuqos1tcorir.jpg"
                },
                "feedback_for_buyer": {
                    "href": "https://reverb.com/api/orders/30/feedback/buyer"
                },
                "feedback_for_seller": {
                    "href": "https://reverb.com/api/orders/20/feedback/seller"
                },
                "listing": {
                    "href": "https://reverb.com/api/listings/20"
                },
                "conversation": {
                    "href": "https://reverb.com/api/my/conversations/20"
                },
                "start_conversation": {
                    "href": "https://reverb.com/api/my/conversations?listing_id=20&recipient_id=100"
                },
                "web_tracking": {
                    "href": "https://tools.usps.com/go/TrackConfirmAction?qtc_tLabels1=1234567890"
                },
                "web": {
                    "href": "https://reverb.com/my/selling/orders/20"
                },
                "web_listing": {
                    "href": "https://reverb.com/item/6611447-fulltone-full-drive-2-mosfet"
                },
                "self": {
                    "href": "https://reverb.com/api/my/orders/selling/20"
                },
                "mark_picked_up": {
                    "href": "https://reverb.com/api/my/orders/selling/20/mark_picked_up"
                },
                "payments": {
                    "href": "https://reverb.com/api/my/payments/selling?order_id=20"
                },
                "contact_buyer": {
                    "web": {
                        "href": "https://reverb.com/my/messages/new?item=20-fulltone-full-drive-2-mosfet&to=30&token=4448b5af4d33d3d7ec7831310609a27e8315320642399c897c506216284f8426"
                    }
                }
            }
        }
    ],
    "_links": {}
}

List of Order Statuses

These are the possible values for the status field:

unpaidBuyer has not submitted payment (usually for Auctions or Offer-based orders, there is a short delay until buyer pays).
payment_pendingPayment has been submitted but is waiting to clear through the payment processor.
pending_reviewOrder is being reviewed for fraud risk. If an order is being reviewed for fraud, the payment has not cleared and it should not be shipped yet.
blockedOrder has been blocked due to potential fraud.
paidOrder is fully paid and cleared for shipment.
shippedOrder has been marked shipped by the seller.
picked_upOrder has been marked picked up by the seller (local pickup orders only).
receivedOrder has been marked received by the buyer (if the seller has not otherwise marked it shipped).
refundedOrder was refunded by the seller. This is a temporary state that leads to cancelled immediately afterwards.
cancelledOrder has been cancelled by seller or buyer request, or because it was fully refunded.

List of Shipping Methods

shippedNormal ground shipping. The item should be marked shipped with a tracking number within 72 hours.
localThis order will be picked up by the buyer at the seller's location.
expedited_shipping2-day expedited shipping. The item should be marked shipped within 24 hours and sent via a 2-day shipping method (method varies depending on carrier).

Other Ways to Access Your Orders

Fetch all orders on the account:

curl -XGET 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/orders/selling/all

Fetch Unpaid orders (newest first):

curl -XGET 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/orders/selling/unpaid

Fetch orders Awaiting Shipment:

curl -XGET 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/orders/selling/awaiting_shipment

Fetch orders by Order Number:

curl -XGET 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/orders/selling/[order_id]

Order Actions

When you retrieve an Order you will see a section in the body of your call with the value "_links". This section contains a series of href attributes with endpoints and URLs that allow you to take specific actions on the Order:

ValueAction
"photo"View the images that are included in the listing.
"feedback_for_buyer"Leave feedback for the buyer or fetch existing feedback you've left for the buyer.
"feedback_for_seller"Fetch feedback that the buyer has left for you.
"listing"Fetch information about the listing.
"conversation"Fetch and reply to messages from the buyer.
"start_conversation"Send a message to the buyer (if no other messages have been exchanged yet).
"web"View the Order within the Reverb UI in your browser.
"web_listing"View the listing within the Reverb UI in your browser.
"self"Fetch details about the Order.
"mark_picked_up"Mark the Order as "picked up" by the buyer.
"ship"Mark the Order as shipped.
"payments"Fetch payment details about the Order.
"contact_buyer"View your conversation with the buyer within the Reverb UI in your browser.
"purchase_shipping_label"Purchase a shipping label from within the Reverb UI in your browser.
"packing_slip"View the packing slip for the Order in your browser.