Manage fulfillments with Fulfillment and FulfillmentService resources

This guide explains how to use the Fulfillment and FulfillmentService resources to create and complete fulfillments. You can use these resources either separately or in tandem, depending on your use case.

Fulfillment resources

Before you create fulfillments, it's helpful to understand some of the different fulfillment-related resources:

• Order: Contains information about an order, including an array of the line items that were purchased. Line items contain important fulfillment information, such as the associated variant, the quantity purchased, and the fulfillment status.

• Location: Represents a geographical location where a line item can be fulfilled. A fulfillment service always has its own location, and variants managed by the fulfillment service should always be fulfilled from that location.

• Fulfillment: Represents a shipment of one or more items in an order. It includes the line item that the fulfillment applies to its tracking information, and the location of the fulfillment.

• FulfillmentService: Represents a third-party warehousing service that prepares and ships orders on behalf of the store owner. Each fulfillment service is associated with its own location. When you create a fulfillment service, a new location is automatically created and associated with it.

Create a fulfillment

The following steps walk through the process of identifying a line item in an order that needs to be fulfilled and then creating a fulfillment.

• Step 1: Query the order to see its line items

• Step 2 Query the variant for its inventory item

• Step 3: Create the fulfillment

• Step 4: Complete the fulfillment

Tip

Each order includes line items that may be stocked at one or more locations. This means that when you create a fulfillment, you need to specify where you are fulfilling. This helps ShopBase effectively manage inventory for the shop owner.

Step 1 Query the order to see its line items

To get started, retrieve the line items of the order that you want to create fulfillment for.

GET https://shop-name.onshopbase.com/admin/orders/{order_id}.json

Response

{
...
  "line_items":[
         {
            "applied_discount":null,
            "custom":true,
            "discount_allocations":[
               {

               }
            ],
            "discount_amount":0,
            "fulfillable_quantity":2,
            "fulfillment_id":0,
            "fulfillment_service":"shopbase",
            "fulfillment_status":"",
            "gift_card":false,
            "id":7256864,
            "image_src":"",
            "line_item_discount_amount":0,
            "line_item_discount_price":0,
            "line_item_price":200,
            "line_item_price_after_discount":100,
            "line_item_price_before_discount":200,
            "line_item_weight":0,
            "name":"Big Brown Bear Boots",
            "price":100,
            "product_id":0,
            "properties":null,
            "quantity":2,
            "raw_price":100,
            "raw_weight":0,
            "requires_shipping":true,
            "sku":"",
            "tax_amount":6,
            "variant_id":1000000125465789,
            ...
      }
    ],
    "fulfillments": [],
  }
}

For more detail, read through the instruction in this link.

Remember to include this code in the test tab for the GET Request:

let response = pm.response.json()
if (response.order.line_items[0].length > 0){
 pm.globals.set("variant_id", response.order.line_items[0].variant_id) 
  }

Step 2: Query the variant for its inventory item (optional)

After you've queried the order's line items, you can use variant IDs to find the specific variants that are associated with the inventory item that you want to fulfill.

If an order contains line items without product or variant IDs, then those items can be fulfilled using any of the shop's locations.

GET https://shop-name.onshopbase.com/admin/variants/{{variant_id}}.json

SAMPLE RESPONSE

{
   "variant":{
      "barcode":"9 788073 400972",
      "compare_at_price":200,
      "cost_per_item":0,
      "created_at":"2020-12-16T19:22:07+00:00",
      "fulfillment_service":"shopbase",
      "grams":0,
      "id":1000003658118088,
      "image_id":434522,
      "inventory_management":"shopbase",
      "inventory_policy":"string",
      "inventory_quantity":100,
      "is_default":true,
      "option1":"IPOD2008PINK",
      "option2":"",
      "option3":"",
      "position":1,
      "presentment_prices":[
         {
            "compare_at_price":{
               "amount":"200",
               "currency_code":"USD"
            },
            "price":{
               "amount":"100",
               "currency_code":"USD"
            }
         }
      ],
      "price":100,
      "product_id":1000000125465789,
      "requires_shipping":true,
      "sku":"string",
      "taxable":true,
      "title":"IPod Nano - 8GB",
      "updated_at":"2020-12-16T19:22:07+00:00",
      "weight":12,
      "weight_unit":"lb"
   }
}

Step 3: Create the fulfillment

To create a fulfillment, pass this following request URL, and set the line_items id to the line_items id above.

POST https://shop-name.onshopbase.com/admin/orders/{order_id}/fulfillments.json

{
   "fulfillment":{
      "line_items":[
         {
            "id":7256864,
            "quantity":12
         }
      ],
      "service":"shopbase",
      "tracking_company":"Other",
      "tracking_number":"123123123",
      "tracking_url":"https://t.17track.net/en#nums=123123123"
   }
}

RESPONSE SAMPLE

{
   "fulfillment":{
      "created_at":"2020-12-17T10:31:02+00:00",
      "detected_tracking_company":"",
      "first_tracking_step_at":0,
      "id":11685344,
      "last_crawled_at":0,
      "last_mile_tracking_company":"",
      "last_mile_tracking_number":"",
      "last_tracking_step_at":0,
      "line_items":[
         {
            "applied_discount":null,
            "compare_at_price":0,
            "custom":true,
            "discount_allocations":[
               {
                  "amount":0,
                  "discount_application_index":0
               }
            ],
            "discount_amount":0,
            "fulfillable_quantity":0,
            "fulfillment_id":0,
            "fulfillment_service":"shopbase",
            "fulfillment_status":"fulfilled",
            "gift_card":false,
            "has_custom_options":false,
            "id":7256864,
            "image_src":"",
            "item_discount_price":0,
            "line_item_discount_amount":0,
            "line_item_discount_price":0,
            "line_item_price":0,
            "line_item_price_after_discount":0,
            "line_item_price_before_discount":0,
            "line_item_price_with_explicit_discount":0,
            "line_item_weight":0,
            "metadata":{
               "is_post_purchase":false,
               "source":null
            },
            "name":"Big Brown Bear Boots",
            "not_explicit_discount_price":0,
            "order_id":5577110,
            "price":100,
            "product_id":0,
            "product_type":"",
            "properties":null,
            "quantity":2,
            "raw_price":100,
            "raw_weight":0,
            "refunded_quantity":0,
            "removed_quantity":0,
            "requires_shipping":true,
            "sku":"",
            "tags":"",
            "tax_amount":0,
            "tax_lines":null,
            "tax_rate":0,
            "taxable":true,
            "tip_payment_gateway":"",
            "tip_payment_method":"",
            "title":"Big Brown Bear Boots",
            "total_discount":0,
            "total_item_discount_price":0,
            "total_line_with_discount_price":0,
            "total_tax_amount":0,
            "variant_id":0,
            "variant_options":"",
            "variant_title":"Big Brown Bear Boots",
            "vendor":"",
            "weight":0,
            "weight_unit":""
         }
      ],
      "name":"#1001.1",
      "notify_customer":false,
      "order_id":5577110,
      "send_delay_mail":false,
      "service":"shopbase",
      "shipment_status":"",
      "status":"success",
      "tracking_company":"Other",
      "tracking_number":"123123123",
      "tracking_numbers":[
         "123123123"
      ],
      "tracking_steps":{         
      },
      "tracking_url":"https://t.17track.net/en#nums=123123123",
      "tracking_urls":[
         "https://t.17track.net/en#nums=123123123"
      ],
      "updated_at":"2020-12-17T10:31:02+00:00",
      "variant_inventory_management":"shopbase"
   }
}

Step 4: Complete a fulfillment

In this final step, we already got the fulfillment id (11685344) and the related order. All that is left to be done is sending a POST method to this request URL:

POST

https://shop-name.onshopbase.com/admin/orders/{order_id:\[0-9\]+}/fulfillments/{fulfillment_id:\[0-9\]+}/complete.json

NOTE:

If you are using a ShopBase store without fulfillment services, the fulfillment status will be automatically set to fulfilled. Therefore, the complete fulfillment API only applies to orders created from Fulfillment Services like Printhub or Ali Dropship Connector.