Merchant API

The intended audience of the Merchant API are partners that sell inventory. The following sections of this document cover each area that may be integrated to automate the entire fulfillment life cycle. Each section consists of a brief summary and a few use cases to demonstrate how the API could be used within your environment. Use cases are for demonstration purposes only, and are not intended to cover every possible error state.

Download our postman collection to see how the endpoints can be used.

Inventory – List and manage your inventory.

Inventory is the most flexible of the subsystems with respect to required data points. We have found every partner has various degrees of data that can be shared in an automated fashion, so we have designed our process with that in mind. Some partners may only have the ability to send a SKU and Quantity in an automated fashion to keep availability up to date. This is acceptable. It only requires you complete the item within the web application. Once the item is completed the API may be used to keep the available quantity synchronized. For those partners with a more complete catalog will allow for a more fluid listing process. Below are diagrams that cover common use cases when working with our API. Click here for more details on the available services.

Use Case 1: Create or update inventory items.

Use Case 2: Monitor listed inventory items and update cost if it has changed.

Orders – An item has sold. How do we get the order details, acknowledge, ship, and invoice.

The order services provide a number of mechanisms to not only monitor for new orders, but also describe the current state of the order within your work flow.  Once an order is received it is expected an acknowledgement will be sent to confirm receipt of the orders.  The acknowledgement allows for both a confirmation of acceptance or rejection.  If the order was initially accepted, but later it is determined the item cannot shipped a new reject acknowledgement should be applied. Note: Once an item has been rejected it is canceled and cannot be undone.  Upon acceptance it is expected the item(s) will be shipped in a timely manner.  After the item is shipped there 3 ways to invoice. The first options is to post the invoice details using the invoice service, another option is to include the invoice details with the ship service, and the final option is to turn on the ‘Auto Invoice’ property within Settings. Below are diagrams that cover common use cases when working with our API. Click here for more details on the available services.

Use Case 1: Get new orders cut to merchant.

Use Case 2: Order shipped by merchant.

Use Case 3: Order canceled by merchant.

Use Case 4: Order invoiced by the merchant. Described below the order is invoiced using the invoice service, but it may also be invoiced using the ship service.

Shipments – Does Quipt generate your shipment labels?

The shipment services are only necessary if you ‘Ship via Quipt’.  The services allow you to download packing slips and labels attached to your orders. The services also allows fine grained status updates. Using the acknowledgement service shipments can be flagged as printed, ‘On dock’, or picked up. It also allows partners to invoice per shipment. Below are diagrams that cover common use cases when working with our API. Click here for more details on the available service endpoints.

Use Case 1: Get new shipments. Assumption: ‘Orders Use Case 1’ was implemented, and open purchase orders are currently stored in a local data store.

Use Case 2: Invoice completed shipments. Assumption: ‘Orders Use Case 1’ was implemented, and open purchase orders are currently stored in a local data store.

Requests – Something happened to an order, how do we track and manage it?

The request services are the most complex since the work flow is not linear.  Each request type can require more work between each partner, where once an order is placed by a retailer all the work is completed by the merchant. A request can be one of five different types, a return, an intercept, a lost shipment, a partial credit, or a missing accessory. The following section is broken down into 5 areas, one to cover each request type. Click here for more details on the available service endpoints.

Returns

A return has 2 points of initiation. The following diagram describes how the API could be used to manage a channel initiated return. This return type consists of a customer contacting the retailer to request a return, and upon approval the retailer submits a request to Quipt. After this point it is expected the item will be shipped back to the merchant, and upon inspection a credit will be given to the retailer.

The other way to initiate return is using a vendor initiated return. This occurs when an order is returned to the merchant without prior notification, ie a refused shipment. The diagram below describes how the API could be used to implement the workflow.

The following diagrams cover a few of the common use cases when working with our API.

Use Case 1: Get new requests assigned to the merchant.

Use Case 2: Merchant requested archive of a request.

Accounting – A transaction is completed, how do we manage until we are paid and settled?

The accounting services provides the ability to view, pay, and reconcile transactions with each partner. As orders and requests are completed the details are aggregated and placed into a ledger for further management. Below are diagrams that cover common use cases when working with our API. Click here for more details on the available services.

Use Case 1: Get open receivable transactions.

Use Case 2: Apply a payment to receivable transactions.