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.
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.
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.
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}.jsonResponse
{
...
"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)
}
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}}.jsonSAMPLE 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"
}
}
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"
}
}
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.