Batches

Buy Batch Shipments

Finalise (purchase) all shipments associated with the batch.

Due to the variability in upstream services of couriers in terms of reliability, latency and response, when a batch is purchased we treat this as a long-running task. If the upstream provider returns the purchased within a few seconds, we return the purchased batch to the client, represented with the 200 OK status code.

For batches that take longer to purchase, after a few seconds the client will receive a 202 Accepted status response, with the body containing information about the purchased batch that can be used to poll the status of the batch. If the purchased batch is not being used immediately, we recommend using webhook events to be updated on the status of the batch, though you will likely need to store the id returned in the response to correlate requests.

N.B. Attempting to run requests that depend on the batch having been purchased immediately after submitting the purchase request, such as requesting shipment labels or a manifest, will likely lead to a failed request or undefined behaviour. This is due to upstream constraints where eg. shipments must be purchased before labels can be generated. To avoid these errors, only carry out subsequent batch operations after you have confirmed that purchasing of the batch either succeeded or failed.

Path Parameters

Name
id
Type
string
Restrictions
Description
The unique ID of the batch.

Request

POST

/batches/{id}/purchase

curl --request POST \
--url https://api.envoy.one/batches/batch_2iFmwXASMpS3l4IZsauPs8I1eOv/purchase \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "id": "batch_2iFmwXASMpS3l4IZsauPs8I1eOv",
  "service": {
    "carrier": {
      "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "UPS",
      "handle": "ups",
      "description": "United Parcel Service"
    },
    "carrier_service": {
      "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "UPS",
      "handle": "ups",
      "description": "United Parcel Service"
    },
    "carrier_account": {
      "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "UPS",
      "handle": "ups",
      "description": "United Parcel Service"
    }
  },
  "options": {
    "label_format": "png"
  },
  "errors": {
    "type": "rate_error",
    "code": "rates_unavailable",
    "source": "provider",
    "message": "rates are not available for the provided shipment"
  },
  "shipments": {
    "id": "shp_0ujzPyRiIAffKhBux4PvQdDqMHY",
    "addresses": {
      "destination": {
        "address": {
          "line_1": "29 Holgate Rd",
          "line_2": "Segwick Street",
          "line_3": "Kelvedon",
          "city": "RACKWICK",
          "province": "Cambershire",
          "post_code": "KW16 2PE",
          "country_code": "GB"
        },
        "contact": {
          "name": "Francesca Brady",
          "company": "Malvinex Corp"
        },
        "display_name": "Work",
        "metadata": {
          "contact_email": "[email protected]"
        },
        "marketplaces": {
          "shopify": "657847832011"
        },
        "coordinates": {
          "latitude": 51.5134297,
          "longitude": -0.103145,
          "confidence": 1
        }
      },
      "origin": {
        "address": {
          "line_1": "29 Holgate Rd",
          "line_2": "Segwick Street",
          "line_3": "Kelvedon",
          "city": "RACKWICK",
          "province": "Cambershire",
          "post_code": "KW16 2PE",
          "country_code": "GB"
        },
        "contact": {
          "name": "Francesca Brady",
          "company": "Malvinex Corp"
        },
        "display_name": "Work",
        "metadata": {
          "contact_email": "[email protected]"
        },
        "marketplaces": {
          "shopify": "657847832011"
        },
        "coordinates": {
          "latitude": 51.5134297,
          "longitude": -0.103145,
          "confidence": 1
        }
      },
      "return": {
        "address": {
          "line_1": "29 Holgate Rd",
          "line_2": "Segwick Street",
          "line_3": "Kelvedon",
          "city": "RACKWICK",
          "province": "Cambershire",
          "post_code": "KW16 2PE",
          "country_code": "GB"
        },
        "contact": {
          "name": "Francesca Brady",
          "company": "Malvinex Corp"
        },
        "display_name": "Work",
        "metadata": {
          "contact_email": "[email protected]"
        },
        "marketplaces": {
          "shopify": "657847832011"
        },
        "coordinates": {
          "latitude": 51.5134297,
          "longitude": -0.103145,
          "confidence": 1
        }
      },
      "location_configuration_id": "lc_2iFuzwcptRh9xt93ICDzK0vOszc"
    },
    "tax_identifiers": [
      {
        "taxable_entity_type": "sender",
        "identifier_type": "ioss",
        "value": "IM0123456789",
        "issuing_country_code": "string"
      }
    ],
    "packages": [
      {
        "name": "string",
        "geometry": {
          "length": null,
          "width": null,
          "height": null,
          "mass": 0
        },
        "predefined_package_code": "string"
      }
    ],
    "customs": {
      "contents_type": "merchandise",
      "contents_description": "automobile parts",
      "declarant": {
        "name": "string",
        "certify": true,
        "date": "string"
      },
      "incoterm": "DDP",
      "restriction_type": "other",
      "restriction_description": "string",
      "declaration_message": "string",
      "items": null,
      "identifiers": [
        {
          "entity_type": "[",
          "identifier_type": "[",
          "value": "string",
          "issuing_country_code": null
        }
      ]
    },
    "options": {
      "shipping": {
        "access_code": "473281",
        "commercial_address": false,
        "currency_code": "USD",
        "date": "2022-07-11T00:00:00.00Z",
        "delivery_confirmation": false,
        "dry_ice_mass": 2500,
        "dropoff_type": "regular_pickup",
        "handling_instructions": "Leave behind plant pot in front porch.",
        "high_security": true,
        "hold_for_pickup": false,
        "invalid_address_handling": "forward_or_return",
        "is_return": false,
        "leave_safe": true,
        "machinable": true,
        "non_delivery": "return",
        "restricted_substances": [
          "["
        ],
        "safe_place": "Garden Shed",
        "saturday_delivery": false,
        "signature_required": true,
        "signature_type": "standard",
        "tracked_service": true
      },
      "label": {
        "format": "pdf",
        "size": "4x6",
        "custom_data": {
          "text_lines": null,
          "line_codes": null,
          "barcodes": null
        }
      },
      "insurance": {
        "value": 55000,
        "currency_code": "USD"
      }
    },
    "carrier": {
      "carrier_code": "string",
      "service_code": "string",
      "carrier_accounts": [
        "string"
      ]
    },
    "name": "ORDER-273548",
    "documents": [
      {
        "id": "doc_2iBgUNtezju7lmzmfOoJO8cnsVS",
        "type": "label",
        "file_name": "2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png",
        "file_type": "image/png",
        "file_size": 129842,
        "file_url": "https://envoy-shipment-files.s3.amazonaws.com/labels/2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png?AWSAccessKeyId=AKIAY27LA84LC8DHB20X&Signature=kZY1RHl%2BBIClJ0UpjpKtAeqZqJA%3D&Expires=1725464510",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z"
      }
    ],
    "rates": [
      {
        "id": "string",
        "carrier": {
          "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
          "name": "UPS",
          "handle": "ups"
        },
        "carrier_service": {
          "id": "cs_2iBgUNbKrgj7uVrsSiiF5ZhTelp",
          "name": "Express",
          "handle": "express"
        },
        "carrier_account": null,
        "rate": 1650,
        "currency_code": "USD",
        "delivery_days": 3,
        "ship_date": "2024-06-18T14:15:22Z",
        "delivery_date": "2024-06-21T14:15:22Z",
        "guaranteed_delivery_date": "2024-06-22T14:15:22Z"
      }
    ],
    "service": {
      "rate": "rate_2iBgUKWHmQlBjYQyx9fAGMvcCEp",
      "carrier": {
        "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
        "name": "UPS",
        "handle": "ups"
      },
      "carrier_service": {
        "id": "cs_2iBgUOHPuWh0Hvjc81euqKXTW5N",
        "name": "Express",
        "handle": "express"
      },
      "carrier_account": {
        "id": "ca_2iBgUOHPuWh0Hvjc81euqKXTW5N",
        "name": "Main Account",
        "handle": null
      }
    },
    "status": "purchased",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "errors": [
      {
        "type": "rate_error",
        "code": "rates_unavailable",
        "source": "provider",
        "message": "rates are not available for the provided shipment"
      }
    ]
  },
  "error_count": 0,
  "packages_count": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

undefined

Batches

Properties

Possible Enum Values

Query Parameters

Request

Response

Request

Response

Path Parameters

Request

Response

Path Parameters

Request

Response

Path Parameters

Request

Response

Path Parameters

Request

Response

Path Parameters

Request

Response

Path Parameters

Query Parameters

Request

Response

Path Parameters

Request

Response

Path Parameters

Request

Response

Path Parameters

Request

Response