API for Order Fulfillment and Management

APIs for order fulfillment and management can be a game-changer for businesses, helping them streamline their operations and improve customer satisfaction.

A well-designed API can automate tasks such as inventory management, shipping, and payment processing, freeing up staff to focus on more complex tasks.

By integrating multiple systems and services, APIs can also provide real-time updates and visibility into the order fulfillment process, helping businesses stay on top of orders and resolve issues quickly.

APIs can also help businesses scale more efficiently, handling increased order volumes and customer demand without breaking a sweat.

APIs for order fulfillment are built on a foundation of API basics. An API, or Application Programming Interface, is a set of rules that enables different software systems to communicate with each other.

APIs typically use HTTP requests to send and receive data, with GET requests used to retrieve data and POST requests used to create new data.

APIs also use data formats like JSON and XML to structure and send data between systems.

API access scopes are used to control what a merchant or app can do with fulfillment orders. There are different scopes for different types of access.

The read_merchant_managed_fulfillment_orders and write_merchant_managed_fulfillment_orders access scopes grant access to fulfillment orders assigned to merchant-managed locations.

Fulfillment services usually have the write_assigned_fulfillment_orders access scope, and don't have access to fulfillment orders assigned to merchant-managed locations or locations owned by other fulfillment service apps.

Order management apps will usually request write_merchant_managed_fulfillment_orders and write_third_party_fulfillment_orders access scopes to manage all fulfillment orders on behalf of a merchant.

Here's a summary of the main API access scopes:

Retrieving is an essential part of working with APIs. You can retrieve fulfillment orders assigned to your app's location using the assignedFulfillmentOrders connection.

To access assigned fulfillment orders, your API client must be granted the read_assigned_fulfillment_orders access scope. This is a requirement for fulfilling orders assigned to your app.

You can use the assignmentStatus argument to control whether all assigned fulfillment orders are returned or only those where a merchant has sent a fulfillment request and it has yet to be responded to.

Fulfillment orders can be retrieved in two ways: by getting all assigned fulfillment orders or by getting fulfillment requests for an order. The latter returns all fulfillment requests created for an order, sorted by creation date in ascending order.

Here's a breakdown of the parameters for getting fulfillment requests for an order:

Keep in mind that if an order wasn't found or wasn't routed yet, an empty list of fulfillment requests will be returned.

To make API calls, you'll often need to make a series of PUT calls to the Shipment API.

Moving a shipment through each step in the fulfillment flow requires making a series of PUT calls to the Shipment API with the shipment number and the task being completed by the current step.

These are generally very simple calls, with the appropriate task identified in the endpoint and only a basic request body to confirm the completion of that step.

Before you begin, you'll need to retrieve shipments and their IDs for fulfillment.

You can learn how to do this by referring back to the section on Querying Order Shipments.

Here are some example cURL requests:

Validate Stock

The endpoint for validating stock is not specified in the provided text, but it is implied that a PUT call is made to the Shipment API with a basic request body to confirm the completion of the stock validation task.

To make a PUT call to the Shipment API, you'll need to know the shipment number and the task being completed.

Order fulfillment is a crucial step in the e-commerce process. A fulfillment order is completed by creating a fulfillment, which represents the work done.

For digital products, a merchant or order management app creates a fulfillment once the digital asset has been provisioned. This can be the case with a digital gift card, where the merchant creates a fulfillment once the gift card has been activated.

A merchant or order management app can send a fulfillment request to a fulfillment service, which operates the location, to request that they fulfill the associated items. The fulfillment service can accept or reject this request.

Here's a breakdown of the steps involved in transfer fulfillment:

You can retrieve the fulfillment orders assigned to your app for fulfillment using the assignedFulfillmentOrders connection. This allows you to control whether all assigned fulfillment orders should be returned or only those where a merchant has sent a fulfillment request and it has yet to be responded to.

Fulfillment orders are completed by creating fulfillments, which represent the work done.

For digital products, a merchant or order management app creates a fulfillment once the digital asset has been provisioned, such as activating a digital gift card.

Fulfillment orders can be assigned to a location that is managed by a fulfillment service, in which case a merchant or order management app can send a fulfillment request to the fulfillment service.

A fulfillment service has the option to accept or reject a fulfillment request, and once accepted, the request can no longer be cancelled by the merchant or order management app.

If a shipment can be manually marked as fulfilled, a call can be made to the Shipment API, though not as a task action.

To print a pick list, the endpoint is used once the pick list has been accepted, allowing store associates to collect the shipment items.

After picking, the fulfiller must indicate whether they had all of the shipment items in stock or not, and if not, they must be identified in the request body.

Marking the Provide to Customer step as completed automatically causes the shipment to be marked Fulfilled.

When a merchant assigns a fulfillment order to an app, the app can retrieve the order with the assignedFulfillmentOrders connection. This allows the app to access the fulfillment orders assigned to their locations.

The API client must be granted the read_assigned_fulfillment_orders access scope to access the assigned fulfillment orders. This ensures that the app only has access to the orders they're responsible for.

The app can control whether to return all assigned fulfillment orders or only those where a merchant has sent a fulfillment request and it has yet to be responded to, using the assignmentStatus argument.

Here's a breakdown of the access scopes for fulfillment service apps:

This helps ensure that the app only has access to the orders they're responsible for, and not orders assigned to other locations or merchants.

Transfer is an essential part of order fulfillment, especially when it comes to shipping missing inventory to a pickup location. This process is called Transfer Fulfillment, and it involves a series of steps to ensure that the items are delivered to the customer.

The first step in Transfer Fulfillment is to validate stock, which means checking if the items are available in the warehouse. This is done by making a call to the completed endpoint, which will return a response indicating whether the items are available or not.

The next step is to print the packing slip, which will be included in the shipment package. This is done by making a call to the endpoint that prints the packing slip. Marking the Prepare for Shipment step as completed will cause the shipment to be automatically marked as fulfilled.

If the location has all the requested items available, the simplest version of the call is made to the completed endpoint. However, if some items are not available, a new transfer shipment can be created to fulfill the missing items.

Here's a summary of the Transfer Fulfillment process:

Transfer Fulfillment can be a complex process, but by following these steps and using the correct endpoints, you can ensure that your customers receive their orders on time.

Once the transfer shipment has been received at the pickup location, its stock must be validated to ensure that it includes the correct items and quantities that were requested.

The request body can either indicate that all items were made available or it can indicate that some items are still missing and trigger a new transfer shipment.

Both cases use the same parameter schema as the initial Validate Stock step, but have a different endpoint.

To validate the incoming transfer, send a request to https://t./api/commerce/shipments/{shipmentNumber}/tasks/Validate Incoming Transfer/completed.

If not all items are yet available for fulfillment then the stock level must indicate “partial.”

Order Management is a critical component of the API for order fulfillment, enabling businesses to efficiently manage their orders from start to finish. With the API, you can automate order processing, reducing manual errors and increasing productivity.

The API allows you to integrate with various order management systems, such as inventory management and shipping providers, to streamline order fulfillment. This integration enables real-time updates and automated workflows, ensuring that orders are fulfilled quickly and accurately.

By leveraging the API's order management capabilities, businesses can improve their order fulfillment rates, reduce costs, and enhance customer satisfaction.

To check the status of canceled items in a fulfillment request, use the Get item cancelation status method. This method returns the cancelation status of items in a fulfillment request.

The cancelation status is not yet available for the fulfillment request. You can't cancel an item after it has been shipped or rejected.

The Cancel items method marks some or all items of a fulfillment request as canceled, immediately releasing allocations and making the item unfulfillable.

To retrieve the status of the cancelation, use the Get item cancelation status method.

In case of an order with multiple items having the same product ID, the least expensive one will be picked first. If all items have the same price, a random item will be picked.

Here's an example of how this works:

If you call the canceled items endpoint with only product1, the item priced at USD 10 will be marked as canceled first. If you call the canceled items endpoint again with product1, the remaining item priced at USD 20 will be marked as canceled.

Rejecting items is a crucial part of order management, and it's essential to know the correct procedures to follow.

If an item is no longer available, you can mark it as rejected by calling the Reject items endpoint. This will update the item's status to "rejected" and prevent it from being shipped.

You can provide a rejection reason for each item, such as "no_inventory" for missing inventory or "cannot_fulfill" if the DC is unable to fulfill the request.

The Reject items endpoint only works if the shipment of the fulfillment request has not started. If the shipment has started, you won't be able to reject the items.

Here are some common rejection scenarios and their corresponding error codes:

If you're rejecting items due to missing inventory, you'll need to specify the product IDs of the items that can't be fulfilled. If you're rejecting items due to an inability to fulfill the request, you won't need to specify the product IDs.

Remember to use the Reject items method instead of the deprecated Reject fulfillment request method.

The Shipment API provides a workflowState object that includes information about the current state of the shipment and lists the upcoming tasks of the fulfillment flow. This object is returned in the response body of any GET Shipment API call.

Each task has a name, inputs (or the template for the request body), and booleans indicating whether it's active or completed. The task that's active displays more detailed information, such as an ID and the execution link of the task.

The workflow information updates with each new response after tasks are performed and the shipment changes states. This list is static and doesn't change, regardless of what state the shipment is currently in.

Here are some common workflow calls that can be made to the Shipment API:

The workflow state is a crucial part of the shipment's journey, providing a clear view of the current state and upcoming tasks.

The workflowState object is returned in the response body of any GET Shipment API call, and it includes information about the current state of the shipment and the tasks it needs to go through to be completed.

Each task has a name, inputs (or the template for the request body), and booleans indicating whether it's active (whether the shipment is currently in that state) and completed (whether the shipment has already passed through that state).

The task that's active displays more detailed information, such as an ID, whether the task can be skipped according to the fulfillment flow, and the execution link of the task.

Here's a breakdown of the task information:

The workflow information updates with each new response after tasks are performed and the shipment changes states.

Workflow Calls are the backbone of the fulfillment process, allowing you to move a shipment through its various stages. This can be done by calling specific tasks from the Shipment API.

There are several types of workflow calls, including Complete Workflow Task, Get Workflow Tasks, and Get Workflow Task Counts. These calls are outlined in the API documentation specs.

You can also use workflow calls to revert or skip a current step, which can be useful in cases where the best-case scenario doesn't play out. For instance, you can make a call to revert a task if something goes wrong.

Here are the base workflow calls outlined in the API documentation specs:

Shipment actions are a crucial part of the order fulfillment process, and the API provides several endpoints to help you manage shipments efficiently.

You can create, update, and delete shipment notes separately from order notes. Shipment notes are not copied onto child shipments or order-level data, so they are only displayed for the shipment they were originally added to.

To create a shipment note, you can use the POST /commerce/shipments/{shipmentId}/notes endpoint. This will define the note text, the username, and role of the user creating the note.

You can also update a shipment note using the PUT /commerce/shipments/{shipmentId}/notes/{noteId} endpoint. The request should define the updated note text, username, and role.

To delete a shipment note, you can use the DELETE /commerce/shipments/{shipmentId}/notes/{noteId} endpoint.

The API returns the updated shipment note in a shipmentNotes object from a GET Shipment call.

To update the shipping status of items in a fulfillment request, you can use the Update shipping status endpoint. This marks some or all items as shipped.

Here are some error codes that may be returned when updating the shipping status:

You can also use the Update the status of order items in a fulfillment request endpoint to update the shipment status for items in the specified fulfillment request.

This endpoint requires the following parameters: line_items, tracking_code, carrier, associate_id, and reason.

Here's a summary of the required parameters:

Item Management is crucial for a smooth order fulfillment process. To manage items effectively, you can use the following endpoints:

Canceling an item in an order that is routed to a store for fulfillment requires contacting the support team. If the order contains multiple items with the same product ID, the least expensive one will be picked first, unless all items have the same price, in which case a random item will be chosen.

Building a catalog with the Catalog API is a great way to unlock the full range of capabilities of the Orders API.

Orders that reference catalog IDs for taxes and discounts are automatically calculated and applied to these price modifiers.

Using catalog item variations and other catalog objects can simplify your item management process. By defining catalog objects for line items, line item modifiers, taxes, and discounts, you can ensure that orders are accurately calculated and applied.

Orders with ad-hoc items can still get the correct tax amounts when letting Square automatically apply taxes by using a seller-defined CatalogTax.

The details defined in the catalog, such as the item name, price, and measurement unit, are used when orders reference catalog line items.

Square updates the inventory for those items when orders that reference catalog line items are completed or refunded.

Here are the key advantages of using catalog item variations and other catalog objects:

The product lifecycle is a crucial aspect of item management. It's the stages a product goes through from its conception to its eventual retirement.

A product typically goes through four stages: introduction, growth, maturity, and decline.

During the introduction stage, a new product is launched into the market, and its sales are usually low.

The growth stage is where the product starts to gain popularity, and its sales increase rapidly. This is often accompanied by a significant increase in marketing efforts.

In the maturity stage, the product's sales reach a plateau, and the market becomes saturated.

During this stage, companies often focus on maintaining their market share rather than expanding it.

The decline stage is where the product's sales start to decrease, and it becomes less competitive.

Companies may choose to discontinue the product or rebrand it to revive its sales.

Understanding the product lifecycle helps businesses make informed decisions about their product offerings and resource allocation.

Validating stock is a crucial step in ensuring that the right items are available for fulfillment. There are three possible scenarios: the fulfiller has enough inventory available for the full shipment, the fulfiller only has partial inventory available, or the fulfiller has no inventory in stock and must reject the shipment.

The simplest version of the call is made with the completed endpoint, which is used when the fulfiller has all inventory in stock. This endpoint is https://t./api/commerce/shipments/{shipmentNumber}/tasks/Validate Items In Stock/completed.

If not all items are yet available for fulfillment, the stock level must indicate "partial" as well as whether a transfer should be created to provide the missing items. The request body should also identify the unavailable items.

The fulfiller will also use the completed endpoint for partial inventory, but the request body will be different and will identify the items that are not yet available. This is in contrast to the rejected endpoint, which is used when the fulfiller does not have any items in stock or must reject the shipment for some other reason.

The rejected endpoint is https://t./api/commerce/shipments/{shipmentNumber}/rejected, and the request will provide a reason for the rejection and indicate whether future assignment to this location should be blocked or not.

Item management is a crucial aspect of any business, especially when it comes to shipping and inventory. You can perform various actions on items within a shipment, such as backordering or canceling them.

Backordering items can be done by sending a POST request to the /commerce/shipments/{shipmentNumber}/backorderedItems endpoint. This action allows you to specify the items that are being backordered from the location.

Canceling items, on the other hand, can be done by sending a PUT request to the /commerce/shipments/{shipmentNumber}/canceledItems endpoint. This action also allows you to specify the items that are being canceled.

You can also pick up items by sending a POST request to the /commerce/shipments/{shipmentNumber}/pickedUpItems endpoint. This action is useful when a customer picks up part of the inventory.

Reassigning items can be done by sending a PUT request to the /commerce/shipments/{shipmentNumber}/reassignedItems endpoint. This action allows you to reassign items that have been picked up or canceled.

Items can't be rejected once they have been moved to a fulfilled state. This means you need to take action on items before they reach a fulfilled state to reject them.

Here is a summary of the item management actions:

Item rejection status is a critical aspect of item management, and it's essential to understand how it works. You can get the item rejection status by using the "Get item rejection status" method.

This method returns a list of all rejected items in a fulfillment request, which is useful for checking if an item in a fulfillment request was successfully rejected. Note that this only applies to orders routed to a DC or warehouse for fulfillment.

You cannot reject an item after it has been shipped or canceled. The rejection status is not yet available for the fulfillment request, so you won't see any rejected items in the list.

If an order contains multiple items with the same product ID, the most expensive one will be picked first. If all items have the same price, a random item will be picked.

Here are the possible rejection reasons:

In case of rejection, you may encounter the following errors:

The error response will include the following information:

The Shipment API provides a workflowState object that lists the upcoming tasks of the fulfillment flow for a shipment. This object includes the name, inputs, and booleans indicating whether the task is active and completed.

The workflowState object is returned by any GET Shipment API call, as well as included in the response when editing a shipment or making calls to transition it through the fulfillment states. This means you can use it as a reference for events such as cancellation that don't require the shipment to be in a particular step.

The tasks listed in the workflowState object are the steps the shipment must move through to be completed, and each task has a name, inputs, and booleans indicating its status. The active task displays more detailed information, such as an ID, whether it can be skipped, and the execution link of the task.

Here are the possible error codes when updating the status of order items in a fulfillment request:

The Shipment API also provides guidelines within the response body to assist with transitioning a shipment through each stage of its fulfillment process. This includes the workflowState and _links objects, which are very useful for fulfilling shipments via API.

Updating the shipping status is a crucial step in the fulfillment process. You can mark some or all items of a fulfillment request as shipped using the shipment endpoint.

If you call the shipment endpoint with only one product, such as product1, the item priced at USD 20 will be marked as shipped first. The remaining item priced at USD 10 will be marked as shipped when the endpoint is called again with the same product.

You might receive a duplicate shipment notification, but that doesn't mean it wasn't processed successfully. Use the Get shipping status to check if the shipment notification has been successfully processed.

To ensure the shipment notification is processed, check the Get shipping status. If it was received successfully, you'll know it's on its way.

Here are some potential issues you might encounter when updating the shipping status:

You can update the status of order items in a fulfillment request using the Update Shipment Status API. This API allows you to mark items as shipped or rejected, but be aware that you can't mix shipment and rejection actions on the same call.

To reject a fulfillment request, you must provide the rejection reason "rescinded". This will initiate a re-routing attempt without any changes to inventory levels. If your organization's settings allow rerouting, rejected fulfillment nodes will be downgraded in priority during the routing process.

The platform emits a separate event for each line item that is marked as shipped, not a single event for all items. This should be considered when reconciling these events in the ERP you are using to manage such events.

To update the status of order items, you need to provide the following information:

If you're doing a partial rejection of items in a fulfillment request, the reroute attempt will not happen until all items in the fulfillment request are in a terminal state.