Skip to content
Veeqo, An Amazon company Developers
Login Signup

Purchase a Label

Overview

This guide will step you through the process of purchasing a label with the Veeqo API.

Prerequisites

To purchase a label you must have the following set up on your Veeqo account:

  • A valid order that is ready to ship. You can create/retrieve these on the /orders endpoint.
  • A payment method linked to your account. You must set this up in your Veeqo account settings.

Walk-through

We need to gather some required parameters before we can make our POST request to the /shipping/shipments endpoint. The table below shows you all the required parameters to purchase a label that need to be retrieved, and where they can be obtained from through the API. The other optional parameters that can be included are defined within the Allocation Rates API reference.

Parameter Endpoint
allocation_id /orders/(order_id)
remote_shipment_id /shipping/rates
service_type /shipping/rates
sub_carrier_id /shipping/rates
service_carrier /shipping/rates
total_net_charge /shipping/rates
base_rate /shipping/rates

Order Details

In order to find the allocation_id for the order we wish to buy a label for, we made the following request:

GET https://api.veeqo.com/orders/22334455

Response:

{
    "id": 22334455,
    "cancel_reason": null,
    "send_refund_email": null,
    "cancelled_at": null,
    "created_at": "2025-08-05T09:16:35.594Z",
    ...
    "allocations": [
        {
            "id": 55443322,
            "updated_at": "2025-08-05T09:16:36.802Z",
            "created_at": "2025-08-05T09:16:35.721Z",
            "total_weight": 0,
            "weight_unit": "oz",
            "allocated_by_id": 4444,
            "order_id": 22334455,
            ...
        }
    ],
    ...
}

From this response, we will save:

  • "id": 55443322, which will be used as allocation_id later.

Shipping Rates

After we have an allocation, we can get all the shipping rates for the allocation and choose which one we want to use. Rates that are available for use will be objects in the "available" parameter in the response.

We made the following request:

GET https://api.veeqo.com/shipping/rates/55443322?from_allocation_package=true

Using Carrier Accounts

If you have a carrier account linked to your Veeqo account, it's possible to request rates for that specific account by supplying the shipping_configuration_ids[] query parameter. To find the right Shipping Configuration ID, navigate to the Shipping carrier integrations page, find the carrier account you wish to use and click "Settings". The URL of the Settings page will contain the numeric ID of the selected carrier account.

Once completed, we can make a request for rates with the selected carrier account's ID:

GET https://api.veeqo.com/shipping/rates/55443322?from_allocation_package=true&shipping_configuration_ids[]=234567

Response:

{
  "available": [
    {
      "carrier": "amazon_shipping_v2",
      "name": "amazon_shipping_v2-2295c3aa-af8c-48a0-9f19-cd84d53cbd36",
      "title": "UPS 3 Day Select®",
      "short_title": "UPS 3 Day Select®",
      "title_with_price": "UPS 3 Day Select® - $11.80",
      "total_net_charge": "11.80",
      "total_gross_charge": "11.80",
      "base_rate": "11.80",
      "charges": [
        {
          "price": "$11.80",
          "charge_id": "BASE_RATE",
          "charge_title": "Base Rate",
          "charge_type": "MANDATORY"
        },
        {
          "price": "$5.90",
          "charge_id": "SIGNATURE_CONFIRMATION",
          "charge_title": "Signature confirmation",
          "charge_type": "OPTIONAL"
        },
        {
          "price": "$7.10",
          "charge_id": "ADULT_SIGNATURE_CONFIRMATION",
          "charge_title": "Adult signature confirmation",
          "charge_type": "OPTIONAL"
        }
      ],
      "currency": "$",
      "weight": "1550.9999986993",
      "remote_shipment_id": "prb123abcde",
      "cutoff": "2025-06-10T22:00:00+01:00",
      "mailpiece_shapes": null,
      "liability_amount": null,
      "expected_delivery_days": 4,
      "sub_carrier_id": "UPS",
      "service_carrier": "ups",
      "shipping_service_options": [
        {
          "key": "value_added_service__VAS_GROUP_ID_CONFIRMATION",
          "label": "Confirmation",
          "type": "select",
          "multiple": false,
          "values": [
            {
              "value": "NO_CONFIRMATION",
              "label": "No confirmation",
              "price": 0,
              "currency": "USD"
            },
            {
              "value": "SIGNATURE_CONFIRMATION",
              "label": "Signature confirmation",
              "price": 5.9,
              "currency": "USD"
            },
            {
              "value": "ADULT_SIGNATURE_CONFIRMATION",
              "label": "Adult signature confirmation",
              "price": 7.1,
              "currency": "USD"
            }
          ]
        }
      ]
    }
  ]
}

From this response, we will save:

  • "remote_shipment_id": "prb123abcde", which will be used as remote_shipment_id later.
  • "name": "amazon_shipping_v2-2295c3aa-af8c-48a0-9f19-cd84d53cbd36", which will be used as service_type later.
  • "sub_carrier_id": "UPS", which will be used as sub_carrier_id later.
  • "service_carrier": "ups", which will be used as service_carrier later.
  • "total_net_charge": "11.80", which will be used as total_net_charge later.
  • "base_rate": "11.80", which will be used as base_rate later.

Shipping Service Options

For each entry in the chosen rate's shipping_service_options array, the entry's key needs to be added as a property of the purchase label's shipment object, with a value taken from that entry's values array. The first value can be used as the default for any option with a type of select.

Whether an option is mandatory is service-dependent — the API will not apply a value for you, even when a $0 option exists. Omitting a mandatory option, or sending a value the rate did not offer, will fail with a 400 error and the code INVALID_VALUE_ADDED_SERVICES. Always read the key and value from the rate response — do not hardcode them.

In our example, the rate returned a Confirmation option, so we will save:

  • "key": "value_added_service__VAS_GROUP_ID_CONFIRMATION", which will be added as a property of the shipment object.
  • "value": "NO_CONFIRMATION", our chosen value for it. Choosing a paid value, such as SIGNATURE_CONFIRMATION, would add its price to the total charge.

Purchase Label

Finally, we can make our POST request in shipments to purchase the label on Veeqo:

POST https://api.veeqo.com/shipping/shipments

Payload:

{
  "carrier": "amazon_shipping_v2",
  "shipment": {
    "allocation_id": 55443322,
    "carrier_id": "",
    "remote_shipment_id": "prb123abcde",
    "service_type": "amazon_shipping_v2-2295c3aa-af8c-48a0-9f19-cd84d53cbd36",
    "notify_customer": true,
    "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"
  }
}