Fulfillments

# List Fulfillments

# Example

When you want to retrieve multiple fulfillments, your data property on the result will always be an array even if you don't have any fulfillments.

        const response = await fetch("https://api.packagex.io/v1/fulfillments", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const fulfillments = response.data; //the array of fulfillments
const pagination = response.pagination; //the pagination object

      

# Pagination

If the has_more property on the pagination object is set to true, you know there are more fulfillments in the database that have not been returned to you. The pagination object also has a page property indicating your current offset and a limit property. The total_count property in pagination returns the the total number of fulfillments in the database.

By default the page is set to 1 and the limit is 25.

If we want to query for items 26 - 50, we would request page 2 with a query parameter.

        const response = await fetch("https://api.packagex.io/v1/fulfillments?page=2&limit=25", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const fulfillments = response.data; //the array of items 25 - 50
const pagination = response.pagination; //the pagination object

      

# Filter

You can filter fulfillments by the following properties.

• location_id - Add the ID of one of your locations to get all of the deliveries currently mapped to that location. For example: location_id=loc_czhgjrk5JaVvyATPDbyURp
• status - A comma separated list of fulfillment statuses. Keep in mind comma's in URLs are encoded as %2C, so we recommend using your platforms native URL encoding library. For example: statuses=picked,packed
• recipient_contact_id - This will let you filter all deliveries where the recipient matches the selected contact ID. For example: recipient_contact_id=ctct_rEMzyCyxJzuBzN4LyurAJV
• sender_contact_id - This will let you filter all deliveries where the sender matches the selected contact ID. For example: recipient_contact_id=ctct_rEMzyCyxJzuBzN4LyurAJV
• updated_by - This will let you filter all deliveries where the updated_by property matches the selected ID. For example: updated_by=key_hnNCb17prVGhjYDy5YicZs
• value_added_services - You can filter fulfillments that have a particular value added service. For example: value_added_services=gift_wrapping
• service_levels - Allows you to filter fulfillments that have the specified comma separated service levels. For example: service_levels=in_person_pickup,same_day
• updated_by - You can filter the fulfillments updated by a user. For example: updated_by=user_JzuBzN4LyurAJVczhgjr
• providers - Allows you to filter fulfillments by a comma separated list of providers. For example providers=packagex,self
• providers - Allows you to filter fulfillments by a comma separated list of rate types. For example rate_types=delivery,pickup
• item_id - Allows you to filter fulfillments that have a particular item. For example item_id=item_7gQXiuSFnCRkfPMPk27ZZZ
• parcel_id - Allows you to filter fulfillments that have a particular parcel. For example parcel_id=prcl_2gqXquSFnCRkPPMPk27ZZZ
• type - Allows you to filter fulfillments domestic or international fulfillments. For example type=domestic

In addition to that, date filters are available on the following fields

• created_at - The timestamp at which the fulfillment was created
• updated_at - The timestamp at which the fulfillment was last updated
• complete_at - The timestamp by which the fulfillment must be completed
• finished_at - The timestamp at which the fulfillment was completed

        const response = await fetch(
  "https://api.packagex.io/v1/fulfillments?location=loc_hj7gjrk5JaVvyATPDbyURp&statuses=picked%2Cpacked&recipient_contact_id=ctct_rEMzyCyxJzuBzN4LyurAJV",
  {
    method: "GET",
    headers: {
      "PX-API-KEY": process.env.PX_API_KEY,
      "Content-Type": "application/json",
    },
  }
).then((res) => res.json());

const fulfillments = response.data;
const pagination = response.pagination;

      

# Sorting

Sorting describes in what order you want your responses to come in. You can select an available property by which to sort, as well as the direction.

• order_by - The property by which to sort. Available properties are: created_at, complete_at
• direction - The direction to sort. Available directions are: asc and desc

By default, fulfillments will be sorted by in descending order, meaning the most recently created will be first.

        const response = await fetch("https://api.packagex.io/v1/fulfillments?order_by=created_at&direction=desc", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const fulfillments = response.data;
const pagination = response.pagination;

      

# Search

There are times when filtering is not enough and you want to find a specific fulfillment by some other attribute. In this case, you can do a fuzzy, typo-tolerant search. Below are the properties that are supported by our full text search.

Searchable Properties

• order_number
• recipient_name
• recipient_phone
• recipient_email
• sender_name
• sender_phone
• sender_email
• sku
• gtin

To search, simply provide a string to search by using the search query param. The results will be order by the most relevant first. If you want to highlight matching search results for a frontend, we provide a special property for search-returned fulfillment objects called _search which will have the matched text surrounded with <mark> handles.

Ordering Search Results

By default, search results are ordered by relevance. However, if you include an order_by parameter along with your search query, the results will be ordered by the specified property instead of by relevance.

Relevance Score

Relevance scores are included in the search results by default. Note that this could add up to 10ms of extra time to the request.

        const response = await fetch("https://api.packagex.io/v1/fulfillments?search=jamie%jones", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const fulfillment = response.data[0];