---
title: "Purchase a batch"
method: POST
path: "/batches/{BatchId}/purchase"
tags: ["Batches"]
---

# Purchase a batch

`POST /batches/{BatchId}/purchase`

Purchases an existing batch with a status of `VALID`. 
Once you send a POST request to the purchase endpoint the batch status will change to `PURCHASING`. 
When all the shipments are purchased, the status will change to `PURCHASED` and you will receive a 
`batch_purchased` webhook indicating that the batch has been purchased

## Path parameters

- `BatchId` string, required

## Headers

- `SHIPPO-API-VERSION` string

## Response `202`

Batch

- Batch
  - `default_carrier_account` string, 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_token` string, 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.](/shippoapi/public-api/service-levels)
  - `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](https://docs.goshippo.com/docs/shipments/shippinglabelsizes/). If empty, will use the default format set from [the Shippo dashboard.](https://apps.goshippo.com/settings/labels)
  - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
  - `batch_shipments` BatchShipmentPaginatedList, required — Array of [BatchShipment](/shippoapi/public-api/batches/batchshipment) objects. The response keeps the same order as in the request array.
    - `next` string
    - `previous` string
    - `results` BatchShipment[]
      - `carrier_account` string — Object ID of the carrier account to be used for this shipment (will override batch default)
      - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
      - `servicelevel_token` string — A token that sets the shipping method for the batch, overriding the batch default. Servicelevel tokens can be found [in this list](/shippoapi/public-api/service-levels) or [at this endpoint](/shippoapi/public-api/carrier-accounts/listcarrieraccounts).
      - `messages` unknown[] — List of Shipment and Transaction error messages.
        - unknown
      - `object_id` string, required — Object ID of this batch shipment. Can be used in the remove_shipments endpoint.
      - `shipment` string, required — Object ID of the shipment object created for this batch shipment.
      - `status` 'INVALID' | 'VALID' | 'INCOMPLETE' | 'TRANSACTION_FAILED', required — - `INVALID`: the batch shipment cannot be purchased and will have to be removed, fixed, and added to the batch again - `VALID`: the batch shipment can be purchased - `TRANSACTION_FAILED`: the batch shipment was not able to be purchased and the error will be displayed on the message field - `INCOMPLETE`: the batch shipment has an issue with the Address and will need to be removed, fixed, and added to the batch again
      - `transaction` string — Object ID of the transaction object created for this batch shipment.
  - `label_url` string[], required — An array of URLs each pointing to a merged file of 100 labels each
  - `object_created` string, required — Date and time of Batch creation
  - `object_id` string, required — Unique identifier of the given Batch object
  - `object_owner` string, required — Username of the user who created the Batch object.
  - `object_results` object, required — An object containing the following counts: `creation_succeeded`, `creation_failed`, `purchase_succeeded`, `purchase_failed`
    - `creation_failed` integer, required
    - `creation_succeeded` integer, required
    - `purchase_failed` integer, required
    - `purchase_succeeded` integer, required
  - `object_updated` string, 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
  - `test` boolean

## Other responses

- `400` — Bad request

---

[API](https://skmtc.net/goshippo/apis/shippo-external-api.md) · [All operations](https://skmtc.net/goshippo/apis/shippo-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/goshippo/shippo-external-api/revisions/13280a44853c/schema)