Sign in

v1

latestOpenAPI 3.1.02026-07-2277219695.0 KB
Batches

Add shipments to a batch

Adds batch shipments to an existing batch.

post/batches/{BatchId}/add_shipments

Path parameters

BatchIdstring required

Object ID of the batch

Headers

SHIPPO-API-VERSIONstring
Example:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Request body

carrier_accountstring

Object ID of the carrier account to be used for this shipment (will override batch default)

metadatastring

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

servicelevel_tokenstring

A token that sets the shipping method for the batch, overriding the batch default. Servicelevel tokens can be found in this list or at this endpoint.

Example request

[
  {
    "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
    "metadata": "SHIPMENT #1",
    "servicelevel_token": "fedex_ground",
    "shipment": {
      "extra": {
        "accounts_receivable_customer_account": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "appropriation_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "bill_of_lading_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "COD": {
          "amount": "5.5",
          "currency": "USD",
          "payment_method": "CASH"
        },
        "cod_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "customer_reference": {
          "ref_sort": 1
        },
        "dealer_order_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "dept_number": {
          "ref_sort": 3
        },
        "fda_product_code": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "insurance": {
          "amount": "5.5",
          "currency": "USD"
        },
        "invoice_number": {
          "ref_sort": 2
        },
        "manifest_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "model_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "part_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "po_number": {
          "ref_sort": 2
        },
        "production_code": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "purchase_request_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "rma_number": {
          "ref_sort": 1
        },
        "salesperson_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "serial_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "store_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        },
        "transaction_reference_number": {
          "prefix": "ABC",
          "value": "value",
          "ref_sort": 1
        }
      },
      "metadata": "Customer ID 123456",
      "shipment_date": "2021-03-22T12:00:00Z",
      "address_from": {
        "name": "Shwan Ippotle",
        "company": "Shippo",
        "street1": "215 Clayton St.",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "+1 555 341 9393",
        "email": "shippotle@shippo.com",
        "is_residential": true,
        "metadata": "Customer ID 123456",
        "validate": true
      },
      "address_return": {
        "name": "Shwan Ippotle",
        "company": "Shippo",
        "street1": "215 Clayton St.",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "+1 555 341 9393",
        "email": "shippotle@shippo.com",
        "is_residential": true,
        "metadata": "Customer ID 123456",
        "validate": true
      },
      "address_to": {
        "name": "Shwan Ippotle",
        "company": "Shippo",
        "street1": "215 Clayton St.",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "+1 555 341 9393",
        "email": "shippotle@shippo.com",
        "is_residential": true,
        "metadata": "Customer ID 123456",
        "validate": true
      },
      "customs_declaration": {
        "b13a_filing_option": "FILED_ELECTRONICALLY",
        "certify": true,
        "certify_signer": "Shawn Ippotle",
        "contents_explanation": "T-Shirt purchase",
        "duties_payor": {
          "account": "2323434543",
          "type": "THIRD_PARTY",
          "address": {
            "name": "Patrick Kavanagh",
            "zip": "80331",
            "country": "DE"
          }
        },
        "exporter_identification": {
          "eori_number": "PL123456790ABCDE",
          "tax_id": {
            "number": "123456789",
            "type": "EIN"
          }
        },
        "invoice": "#123123",
        "metadata": "Order ID #123123",
        "address_importer": {
          "name": "Shwan Ippotle",
          "company": "Shippo",
          "street1": "Blumenstraße",
          "street_no": "22",
          "city": "München",
          "state": "CA",
          "zip": "80331",
          "country": "DE",
          "phone": "80331",
          "email": "shippotle@shippo.com",
          "is_residential": true
        },
        "contents_type": "MERCHANDISE",
        "eel_pfc": "NOEEI_30_37_a",
        "incoterm": "DDP",
        "items": [
          {
            "description": "T-Shirt",
            "mass_unit": "lb",
            "metadata": "Order ID \"123454\"",
            "net_weight": "5",
            "quantity": 20,
            "sku_code": "HM-123",
            "hs_code": "0901.21",
            "value_amount": "200",
            "value_currency": "USD"
          }
        ],
        "non_delivery_option": "RETURN",
        "test": true
      },
      "carrier_accounts": [
        "065a4a8c10d24a34ab932163a1b87f52",
        "73f706f4bdb94b54a337563840ce52b0"
      ],
      "parcels": [
        {
          "extra": {
            "COD": {
              "amount": "5.5",
              "currency": "USD",
              "payment_method": "CASH"
            },
            "insurance": {
              "amount": "5.5",
              "content": "Laptop",
              "currency": "USD",
              "provider": "UPS"
            }
          },
          "metadata": "Customer ID 123456",
          "mass_unit": "lb",
          "weight": "1",
          "distance_unit": "in",
          "height": "1",
          "length": "1",
          "width": "1"
        }
      ]
    }
  }
]

Response

Batch

default_carrier_accountstring required

ID of the Carrier Account object to use as the default for all shipments in this Batch. The carrier account can be changed on a per-shipment basis by changing the carrier_account in the corresponding BatchShipment object.

default_servicelevel_tokenstring required

Token of the service level to use as the default for all shipments in this Batch. The servicelevel can be changed on a per-shipment basis by changing the servicelevel_token in the corresponding BatchShipment object. Servicelevel tokens can be found here.

label_filetype'PNG' | 'PNG_2.3x7.5' | 'PDF' | 'PDF_2.3x7.5' | 'PDF_4x6' | 'PDF_4x8' | 'PDF_A4' | 'PDF_A5' | 'PDF_A6' | 'ZPLII'

Print format of the label. If empty, will use the default format set from the Shippo dashboard.

metadatastring

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

label_urlstring[] required

An array of URLs each pointing to a merged file of 100 labels each

object_createdstring required

Date and time of Batch creation

object_idstring required

Unique identifier of the given Batch object

object_ownerstring required

Username of the user who created the Batch object.

object_updatedstring required

Date and time of last update to the Batch

status'VALIDATING' | 'VALID' | 'INVALID' | 'PURCHASING' | 'PURCHASED' required
  • VALIDATING: the batch is being created and validated
  • VALID: the batch can be purchased
  • INVALID: the batch cannot be purchased; INVALID BatchShipments must be removed
  • PURCHASING: the batch is being purchased
  • PURCHASED: the batch is finished purchasing
testboolean

Example response

{
  "default_carrier_account": "078870331023437cb917f5187429b093",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "metadata": "BATCH #1",
  "batch_shipments": {
    "next": "baseurl?page=3&results=10",
    "previous": "baseurl?page=1&results=10",
    "results": [
      {
        "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
        "metadata": "SHIPMENT #1",
        "servicelevel_token": "fedex_ground",
        "object_id": "e11c95a6788d4ddcaa22f03175838740",
        "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
        "status": "INVALID",
        "transaction": "4c33736a67e2450da88b38c42deef6b7"
      }
    ]
  },
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@shippo.com",
  "object_results": {
    "creation_failed": 3,
    "creation_succeeded": 5
  },
  "object_updated": "2016-01-04T00:48:13.841Z",
  "status": "VALID"
}