Orders

Creating Orders

ShipBob’s Order POST endpoint has several required fields that you need to be aware of:

• Shipping method: This is typically a value such as “Standard”, “Expedited”, “2-Day”, etc. Once a ship method comes through via the integration, the merchant will have the ability to map the method to a specific Ship Option that will determine the shipment’s SLA and carrier selection. More detail on Ship Options can be found in our help center here.
• Recipient name - The name of the individual the shipment will be delivered to.
• Recipient address – specifically the Address1, City, and Country (ISO Alpha-2 code is highly recommended). If available, please also pass the State and Zip Code.
• Reference id – This is a unique order number from the upstream platform being integrated with ShipBob. This number must be unique within your ShipBob account.
  You can also pass an optional order_number field. This does not need to be unique, and is a more user-friendly order number that a customer service agent might be more familiar with.
• Products – There are two methods for providing product data with your order payload to ShipBob:
  • ReferenceId Model (highly recommended) – This model allows you to pass a product’s reference_id (typically the SKU value), as well as the product name. When an order is created, ShipBob will check if the product already exists based on a matching reference_id, and will automatically create a new product if one does not already exist.
    This model is recommended as you do not need to store any external ShipBob product id values to create an order successfully. It also has the ability to auto-create products if they do not exist based on the duplicate match of a reference_id value.
  • ProductId Model – This model requires that you pass ShipBob’s ProductId as part of the order payload to create the order. This will mean that you first must create a product using ShipBob’s Product API and have a method to either store or reference the ShipBob-generated ProductId to use as part of your order creation process.
    • This model works best if you always create products in ShipBob prior to sending any orders, and have a way to store the ProductId somewhere upstream.

When viewing the API documentation, you can toggle between each model by expanding the Product node.

In addition to the required fields highlighted above, you also have the ability to pass order tags to ShipBob. Tags are an array that consists of a name, value pair which can be used to store additional data that might be needed with your platform upstream, and can also trigger automation rules that have been created in ShipBob.

More details on available rules can be found here.

To trigger a rule created within ShipBob, the order tag name must match the rule. As an example, if you desire to pass a tag that triggers a rule to automatically add a marketing insert to specific orders, your tag structure may look like:

1
"tags": [
2
  {
3
    "name": "AddMarketingInsert",
4
    "value": "NotUsedForRuleTrigger"
5
  },
6
  {
7
    "name": "Subscription First Order",
8
    "value": "0"
9
  }
10
],

Where the tag “name” value of “AddMarketingInsert” is what will be used to trigger a rule created in ShipBob.

Lastly, you will need to also specify a shipbob_channel_id within the request header to successfully create an order. To find which channel you have write access to, you can call the GET Channel endpoint to view a list of permissions you have access to under each channel. You will only have write access for one channel (your own integration channel), but you typically will have the ability to read data across other channels.

Sample requests

1
{
2
  "shipping_method": "Standard",
3
  "recipient": {
4
    "name": "John Doe",
5
    "address": {
6
      "address1": "120 N Racine Ave",
7
      "address2": "100",
8
      "city": "Chicago",
9
      "state": "IL",
10
      "country": "United States",
11
      "zip_code": "60607"
12
    },
13
    "phone_number": "111-222-3333",
14
    "email": "test@domain.com"
15
  },
16
  "products": [
17
    {
18
      "name": "Light Roast Coffee",
19
      "reference_id": "LIGHT-ROAST",
20
      "quantity": 1,
21
      "unit_price": 19.99
22
    }
23
  ],
24
  "reference_id": "10001",
25
  "order_number": "10001",
26
  "type": "DTC",
27
  "financials": {
28
    "total_price": 25.99
29
  }
30
}

1
{
2
  "shipping_method": "Standard",
3
  "recipient": {
4
    "name": "John Doe",
5
    "address": {
6
      "address1": "120 N Racine Ave",
7
      "address2": "100",
8
      "city": "Chicago",
9
      "state": "IL",
10
      "country": "United States",
11
      "zip_code": "60607"
12
    },
13
    "phone_number": "111-222-3333",
14
    "email": "test@domain.com"
15
  },
16
  "products": [
17
    {
18
      "name": "Light Roast Coffee",
19
      "reference_id": "LIGHT-ROAST",
20
      "quantity": 1,
21
      "unit_price": 19.99
22
    }
23
  ],
24
  "reference_id": "10001",
25
  "order_number": "10001",
26
  "type": "DTC",
27
  "financials": {
28
    "total_price": 25.99
29
  },
30
  "tags": [
31
    {
32
      "name": "Subscription Order",
33
      "value": "0"
34
    },
35
    {
36
      "name": "New Customer",
37
      "value": "0"
38
    }
39
  ]
40
}

1
{
2
  "shipping_method": "Standard",
3
  "recipient": {
4
    "name": "John Doe",
5
    "address": {
6
      "address1": "120 N Racine Ave",
7
      "address2": "100",
8
      "city": "Chicago",
9
      "state": "IL",
10
      "country": "United States",
11
      "zip_code": "60607"
12
    },
13
    "phone_number": "111-222-3333",
14
    "email": "test@domain.com"
15
  },
16
  "products": [
17
    {
18
      "name": "Light Roast Coffee",
19
      "reference_id": "LIGHT-ROAST",
20
      "quantity": 1,
21
      "unit_price": 19.99
22
    }
23
  ],
24
  "reference_id": "10001",
25
  "order_number": "10001",
26
  "type": "DTC",
27
  "financials": {
28
    "total_price": 25.99
29
  },
30
  "location_id": 8
31
}

1
{
2
  "shipping_method": "Standard",
3
  "recipient": {
4
    "name": "John Doe",
5
    "address": {
6
      "address1": "120 N Racine Ave",
7
      "address2": "100",
8
      "city": "Chicago",
9
      "state": "IL",
10
      "country": "United States",
11
      "zip_code": "60607"
12
    },
13
    "phone_number": "111-222-3333",
14
    "email": "test@domain.com"
15
  },
16
  "products": [
17
    {
18
      "name": "Light Roast Coffee",
19
      "reference_id": "LIGHT-ROAST",
20
      "quantity": 1,
21
      "unit_price": 19.99
22
    }
23
  ],
24
  "reference_id": "10001",
25
  "order_number": "10001",
26
  "type": "DTC",
27
  "financials": {
28
    "total_price": 25.99
29
  },
30
  "sales_channel": "tiktok"
31
}

Creating B2B Orders (Without Retailer Compliance)

Orders created here are generic B2B orders. ShipBob will fulfill them using standard packing slips, standard boxes, and standard routing. No retailer-specific labeling, packing configurations, routing requirements, or ASN generation will be applied.

Why? Retailer compliance depends on data carried in EDI purchase orders (label formats, carton rules, routing instructions, ASN requirements). This data is ingested through ShipBob’s EDI integrations and is not available through the public API. If your orders ship to a retailer with compliance requirements, contact your ShipBob point of contact to discuss EDI integration before building against this endpoint.

What this endpoint is for: B2B shipments that do not require retailer-specific compliance — for example, wholesale orders to your own retail locations, distributors, or other businesses without inbound compliance programs.

Generic B2B orders passing through ShipBob’s API must be sent with specific required fields to ensure they fall under our B2B flow as opposed to the default D2C flow.

Attached, you will find an example API request for a general b2b order. While reviewing this example, there are several fields to note within this payload that differ from a standard D2C order:

• Ensure that the type is set to a value of 2 or “B2B” (this denotes a B2B order type).
• carrier_type will be either “Parcel” or “Freight” – recommended that you have the ability to select which of these options should be used.
• payment_terms can either be “Prepaid” or “MerchantResponsible”.
  • This depends if you will be uploading your own labels on the ShipBob dashboard, or if ShipBob will provide the labels. If ShipBob will handle labels, then pass the value “Prepaid”.
• retailer_program_type should be set to “SB-B2B”.
• Pass a purchase_order_number.
• company_name within the recipient address data should be the retailer’s name.
• quantity_unit_of_measure_code should be “EA” for eaches

Sample request

1
{
2
  "shipping_method": "Standard",
3
  "recipient": {
4
    "name": "John Doe",
5
    "address": {
6
      "address1": "100 Nowhere Blvd",
7
      "address2": "Suite 100",
8
      "city": "Gotham City",
9
      "state": "NJ",
10
      "zip_code": "07093",
11
      "country": "US"
12
    },
13
    "email": "test@shipbob.com",
14
    "phone_number": "9998887777"
15
  },
16
  "reference_id": "10001",
17
  "order_number": "10001",
18
  "purchase_date": "2024-09-22T23:00:48Z",
19
  "type": "B2B",
20
  "products": [
21
    {
22
      "name": "Test SKU",
23
      "sku": "test-sku",
24
      "reference_id": "test-sku",
25
      "quantity": 25
26
    }
27
  ],
28
  "retailer_program_data": {
29
    "purchase_order_number": "10001",
30
    "retailer_program_type": "SB-B2B",
31
    "mark_for_store": null,
32
    "department": null,
33
    "delivery_date": null,
34
    "addresses": [],
35
    "customer_ticket_number": null
36
  },
37
  "shipping_terms": {
38
    "carrier_type": "Parcel", // "Parcel" or "Freight"
39
    "payment_term": "Prepaid" // "Prepaid" or "MerchantResponsible"
40
  }
41
}

FAQs

1
{
2
  "shipping_method": "Standard",
3
  "recipient": {
4
    "name": "John Doe",
5
    "address": {
6
      "address1": "100 Nowhere Blvd",
7
      "address2": "Suite 100",
8
      "city": "Gotham City",
9
      "state": "NJ",
10
      "zip_code": "07093",
11
      "country": "US"
12
    },
13
    "email": "test@shipbob.com",
14
    "phone_number": "9998887777"
15
  },
16
  "reference_id": "10001",
17
  "order_number": "10001",
18
  "purchase_date": "2024-09-22T23:00:48Z",
19
  "type": "DTC", // [!code --]
20
  "type": "B2B", // [!code ++]
21
  "products": [
22
    {
23
      "name": "Light Roast Coffee",
24
      "sku": "LIGHT-ROAST",
25
      "reference_id": "LIGHT-ROAST",
26
      "quantity": 25,
27
      "unit_price": 14.99
28
    }
29
  ],
30
  "financials": {
31
    "total_price": 374.75
32
  },
33
  "retailer_program_data": { // [!code ++:13]
34
    "purchase_order_number": "10001",
35
    "retailer_program_type": "SB-B2B",
36
    "mark_for_store": null,
37
    "department": null,
38
    "delivery_date": null,
39
    "addresses": [],
40
    "customer_ticket_number": null
41
  },
42
  "shipping_terms": {
43
    "carrier_type": "Parcel", // "Parcel" or "Freight"
44
    "payment_term": "Prepaid" // "Prepaid" or "MerchantResponsible"
45
  }
46
}