ShipBuy

API 版本
V2 · 新集成V1 · 现有集成

购买面单

详细字段参考以英文显示；字段名和 API 值保持不变。

POST
/api/shipping/buy

请求

client_reference_id
String · No
Customer Unique Reference ID.
shipping_account_name
String · Yes
Name of the shipping account.
carrier_type
String · Yes
Type of shipping carrier, e.g., 'usps'.
service_type
String · Yes
Type of shipping service, e.g., 'usps_priority_mail'.
confirmation_type
String · No
Type of delivery confirmation required, if any.
insurance_provider_type
String · No
Insurance provider type, if insurance is required.
dimension_unit
String · Account default
Unit of measurement for package dimensions, e.g., 'in' for inches. When omitted, the checked controller uses the account setting; sending the unit explicitly is recommended.
weight_unit
String · Account default
Unit of weight for packages, e.g., 'oz' for ounces. When omitted, the checked controller uses the account setting; sending the unit explicitly is recommended.
rate_id
String · No
Unique identifier for a specific rate quote, if applicable.
from.company
String · No
Sender's company name, if applicable.
from.name
String · Yes
Full name of the sender.
from.phone
String · No
Sender's phone number.
from.email
String · No
The historical documentation lists this field, but the checked V1 shipping controller does not forward it. Do not rely on it reaching the carrier.
from.street1
String · Yes
Primary street address of the sender.
from.street2
String · No
Secondary street address of the sender.
from.city
String · Yes
City of the sender's address.
from.state
String · Yes
State of the sender's address.
from.zip
String · Yes
Postal code of the sender's address.
from.country
String · Yes
Country code of the sender's address.
from.residential
Boolean · Yes
Indicates if the sender's address is residential.
to.company
String · No
Recipient's company name, if applicable.
to.name
String · Yes
Full name of the recipient.
to.phone
String · No
Recipient's phone number.
to.email
String · No
The historical documentation lists this field, but the checked V1 shipping controller does not forward it. Do not rely on it reaching the carrier.
to.street1
String · Yes
Primary street address of the recipient.
to.street2
String · No
Secondary street address of the recipient.
to.city
String · Yes
City of the recipient's address.
to.state
String · Yes
State of the recipient's address.
to.zip
String · Yes
Postal code of the recipient's address.
to.country
String · Yes
Country code of the recipient's address.
to.residential
Boolean · Yes
Indicates if the recipient's address is residential.
packages[].package_type
String · No
Type of package.
packages[].length
Number · Yes
Length of the package.
packages[].width
Number · Yes
Width of the package.
packages[].height
Number · Yes
Height of the package.
packages[].weight
Number · Yes
Weight of the package.
packages[].insurance_amount
Number · No
Amount of insurance for the package.
options.ship_date
Date String · Yes
The date the shipment is to be made.
options.print_custom1
String · No
Custom printing field 1.
options.print_custom2
String · No
Custom printing field 2.
options.label_format
String · No
png or pdf, png as default
options.label_data_type
String · No
url or raw, url as default
customs.contents_type
String · Yes
Type of contents, e.g., 'merchandise'.
customs.contents_explanation
String · Yes
Explanation of the contents.
customs.non_delivery_option
String · Yes
Action to take if delivery is not possible, e.g., 'return'.
customs.eel_pfc
String · No
Electronic Export Information or Proof of Filing Citation.
customs.certify
Boolean · No
Indicates whether the sender certifies the information.
customs.signer
String · Yes
Name of the person signing the customs declaration.
customs.items[].description
String · Yes
Description of the item.
customs.items[].quantity
Number · Yes
Quantity of the item.
customs.items[].value
Number · Yes
Value of the item.
customs.items[].currency
String · Yes
Currency of the item's value.
customs.items[].weight
Number · Yes
Weight of the item.
customs.items[].weight_unit
String · Yes
Unit of weight for the item.
customs.items[].tariff_number
String · No
Harmonized Tariff Schedule number for the item.
customs.items[].origin_country
String · Yes
Country of origin for the item.
{
  "shipping_account_name": null,
  "dimension_unit": "in",
  "weight_unit": "lb",
  "from": {
    "name": "Sender",
    "street1": "100 Example St",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001",
    "country": "US"
  },
  "to": {
    "name": "Recipient",
    "street1": "200 Example Ave",
    "city": "San Diego",
    "state": "CA",
    "zip": "92101",
    "country": "US",
    "residential": true
  },
  "packages": [
    {
      "length": 10,
      "width": 8,
      "height": 6,
      "weight": 2
    }
  ],
  "rate_id": "<returned-rate-id>",
  "client_reference_id": "<your-stable-reference>",
  "options": {
    "label_format": "pdf",
    "label_data_type": "url"
  }
}

返回结果

id
Integer
Unique identifier for the shipping label.
tracking_number
String
Tracking number of the shipping label.
shipping_account_name
String
Name of the shipping account used.
carrier_type
String
Type of shipping carrier (e.g., 'usps').
service_type
String
Type of shipping service (e.g., 'usps_ground_advantage').
insurance_provider_type
String or Null
Insurance provider type, if applicable.
insurance_cost
Number
Cost of the insurance, if any.
shipping_cost
Number
Cost of shipping.
currency
String
Currency of the shipping cost (e.g., 'usd').
dimension_unit
String
Unit of dimension for packages (e.g., 'in').
weight_unit
String
Unit of weight for packages (e.g., 'oz').
delivery_days
Integer
Estimated number of days for delivery.
delivery_date
String or Null
Estimated delivery date, if available.
ship_date
String
Date when the shipment was made.
from.name
String
Sender's full name.
from.company
String or Null
Sender's company name.
from.phone
String or Null
Sender's phone number.
from.email
String or Null
Sender's email address.
from.street1
String
Primary street address of the sender.
from.street2
String or Null
Secondary street address of the sender.
from.city
String
City of the sender's address.
from.state
String
State of the sender's address.
from.zip
String
Postal code of the sender's address.
from.country
String
Country code of the sender's address.
from.residential
Boolean
Indicates if the sender's address is residential.
to.name
String
Recipient's full name.
to.company
String or Null
Recipient's company name.
to.phone
String or Null
Recipient's phone number.
to.email
String or Null
Recipient's email address.
to.street1
String
Primary street address of the recipient.
to.street2
String or Null
Secondary street address of the recipient.
to.city
String
City of the recipient's address.
to.state
String
State of the recipient's address.
to.zip
String
Postal code of the recipient's address.
to.country
String
Country code of the recipient's address.
to.residential
Boolean
Indicates if the recipient's address is residential.
packages[].package_type
String or Null
Type of package.
packages[].insurance_amount
Number
Amount of insurance for the package.
packages[].length
Number
Length of the package.
packages[].width
Number
Width of the package.
packages[].height
Number
Height of the package.
packages[].weight
Number
Weight of the package.
packages[].tracking_number
String
Tracking number for the package.
packages[].label_url
String
URL for the shipping label of the package.
forms[].type
String
Type of the form, e.g., 'commercial_invoice'.
forms[].url
String
URL to access the form.
created_at
String
Timestamp of when the label was created.

V1 responses use the original endpoint-specific JSON structure. Do not wrap them in the V2 code/message/data envelope.

接入说明

Send the same shipping plan with the selected rate_id. A client_reference_id allows the existing V1 controller to return a matching shipment rather than buy again. If another purchase holds the lock, it returns HTTP 202 with status purchasing and retry_after. For an uncertain result, preserve the same reference and confirm the existing shipment before creating a new purchase. Default label_format is png and label_data_type is url; pdf/raw are explicit options. This V1 behavior is not V2 Idempotency-Key.