Purchase Shipping Labels
POST /shipping/shipments
Purchase a shipping label for an order’s allocation. Ensure you fetch rates first via Retrieve Shipping Rates, then copy your chosen quote’s fields into the matching shipment field.
Request Body required
Section titled “Request Body required ”object
The carrier for which the shipping label is being purchased.
amazon_shipping_v2ID of the linked carrier account the chosen quote came from. Take it from linked_accounts[] in the rates response: the entry whose carrier is amazon_shipping_v2__ + the quote’s sub_carrier_id (e.g. amazon_shipping_v2__FEDEX). Send it as a string. Required in practice when you requested rates with shipping_configuration_ids[]; if omitted, Veeqo selects the account itself (preferred, recommended, then default account), which may not be the one that quoted. An ID that is not one of your accounts returns 400 Invalid shipping configuration.
123456Details of the shipment to purchase. Copy the values from your chosen quote in the rates response.
object
The ID of the allocation to purchase the shipping label for. Retrieve this from the allocations array in the GET /orders/{order_id} response.
Not used when buying a label - the carrier comes from top-level carrier and the account from top-level shipping_configuration_id. Send an empty string or omit it.
The chosen quote’s remote_shipment_id from the rates response. Length may vary.
The chosen quote’s name from the rates response.
Whether to send the customer a shipping confirmation for this shipment. When true, Veeqo emails the customer, or - on channels where Veeqo does not send notifications - asks the sales channel to notify them. Optional; if omitted it is false. Veeqo’s web app defaults it to the sales channel’s shipment-email setting and lets the seller change it per order.
Overrides the channel’s tracking sync for the order while this is its newest shipment. true forces the push on, false forces it off, and omitting it (or sending null) defers to the channel’s own update_remote_order. This is an override, not the primary control which exists on the channel setting.
The chosen quote’s sub_carrier_id from the rates response, e.g. UPS or USPS.
The chosen quote’s service_carrier from the rates response, e.g. ups or usps.
Payment method ID, if applicable.
Liability amount for insurance, if applicable. Valid bounds are given by the liability_amount entry in the chosen quote’s shipping_service_options.
Whether to create a return label.
The chosen quote’s total_net_charge from the rates response.
The chosen quote’s base_rate from the rates response.
The chosen quote’s expires_at (ISO 8601). If it is in the past the purchase fails with The selected rate has expired. Please refresh rates.
Additional optional services can be included using keys from the shipping_service_options array in the rates response.
Value-added services use the pattern value_added_service__* (e.g., value_added_service__VAS_GROUP_ID_CONFIRMATION)
Additional inputs use the pattern additional_input__* (e.g., additional_input__SHIPMENT_DESCRIPTION)
Common examples:
value_added_service__VAS_GROUP_ID_CONFIRMATION: “SIGNATURE_CONFIRMATION” or “DELIVERY_CONFIRMATION”additional_input__SHIPMENT_DESCRIPTION: “Fragile electronics”
The available options and their valid values are returned in the shipping_service_options array from the rates endpoint.
If the selected rate includes a non-optional service, you should pass the option with a valid value from
its values array. Omitting a required service, or sending a value the rate did not offer, fails with INVALID_VALUE_ADDED_SERVICES.
Example
{ "carrier": "amazon_shipping_v2", "shipping_configuration_id": "123456", "shipment": { "allocation_id": 55443322, "carrier_id": "", "remote_shipment_id": "123abcde-5f41-4d82-9b06-3c7e8a1d5f40", "service_type": "amazon_shipping_v2-2295c3aa-af8c-48a0-9f19-cd84d53cbd36", "notify_customer": false, "sub_carrier_id": "UPS", "service_carrier": "ups", "payment_method_id": null, "value_added_service__VAS_GROUP_ID_CONFIRMATION": "NO_CONFIRMATION", "try_inbound_label": false, "total_net_charge": "11.80", "base_rate": "11.80" }}Responses
Section titled “ Responses ”Successful response with purchased shipping labels.
object
The ID of the shipment. Pass it to Retrieve Shipping Labels.
object
The currency unit for the charges.
The total charge for the shipping label.
The shipment’s tracking record, or null when the service is untracked. Read the tracking number from tracking_number.tracking_number (string); the other properties are internal.
object
The ID of the tracking record.
The carrier’s tracking number.
URL to track the shipment.
Relative path to the label on this API host, of the form /shipping/labels?shipment_ids%5B%5D=<id> (see Retrieve Shipping Labels). null when no label file was stored.
Relative path to the commercial invoice on this API host. null when there is none.
Whether a return label was created for this shipment.
Example
{ "id": 123456789, "outbound_label_charges": { "unit": "USD", "value": 8.56 }, "tracking_number": { "id": 987654321, "tracking_number": "1Z999AA10123456784" }, "tracking_url": "<TRACKING_URL>", "label_url": "/shipping/labels?shipment_ids%5B%5D=123456789", "commercial_invoice_url": null, "has_return_label": false}Bad request. Ensure you are passing valid parameters. Returned with error code INVALID_VALUE_ADDED_SERVICES when a mandatory value-added service group is omitted, or a value not offered by the chosen quote is sent. Check the shipping_service_options array of the chosen quote in the rates response.
Example
{ "error_messages": [ "InvalidRequestException, errorCode: INVALID_VALUE_ADDED_SERVICES, errorMessage: The requested value added services are invalid. Please check the value added services offered in the GetRates response." ]}Allocation ID not found or invalid shipping rates provided.
Internal server error during label purchase.