Drafts

Check for imported orders

POST /v1/imports/lookup

Which of the given order ids this account has already imported, so an import can skip them.

Request body

• order_ids • Required array of strings

  Order ids to check.

Response in data

• items • Required array of objects
  Each item · 8

  • imported_at • Required timestamp
  • order_id • Required string
  • status • Required string
  • draft_id uuid
  • shipment_id uuid
  • source string

    Where the shipment came from. Leave out (it becomes manual) or name your integration, e.g. api.

  • step string
  • tracking_number string

    The carrier's tracking number.

Save a draft

POST /v1/shipments/draft

Saves a shipment without buying it. A draft can hold a chosen rate, and be bought later with POST /v1/shipments/draft/{id}/process.

Request body

• from • Required object

  Ship-from address.

  Fields · 11

  • city • Required string

    City.

  • country • Required string

    Two-letter country code, e.g. CA, US.

  • name • Required string
  • postal_code • Required string

    Postal or ZIP code.

  • state • Required string

    Province or state code, e.g. ON, BC, NY.

  • street • Required string

    Street address.

  • company string

    Company name.

  • email string

    Email address.

  • is_residential boolean

    True for a home address. Some carriers charge more for residential delivery.

  • line2 string

    Apartment, suite or unit.

  • phone string

    Phone number. Carriers need one for the recipient on most international and express services.

• to • Required object

  Ship-to address.

  Fields · 11

  • city • Required string

    City.

  • country • Required string

    Two-letter country code, e.g. CA, US.

  • name • Required string
  • postal_code • Required string

    Postal or ZIP code.

  • state • Required string

    Province or state code, e.g. ON, BC, NY.

  • street • Required string

    Street address.

  • company string

    Company name.

  • email string

    Email address.

  • is_residential boolean

    True for a home address. Some carriers charge more for residential delivery.

  • line2 string

    Apartment, suite or unit.

  • phone string

    Phone number. Carriers need one for the recipient on most international and express services.

• batch_id uuid

  A batch from GET /v1/batches.

• delivery_instructions string

  Instructions for the driver.

• email_notifications boolean

  Email tracking updates to the recipient.

• packages array of objects

  One entry per box.

  Each item · 10

  • dimension_unit • Required string

    in or cm.

  • height • Required number

    Height, in dimension_unit.

  • items • Required array of objects

    What is in this box (optional for domestic shipments).

    Each item · 8

    • currency • Required string

      Three-letter currency code, e.g. CAD.

    • description • Required string

      What the item is.

    • quantity • Required integer

      How many.

    • unit_value_cents • Required integer

      Value of one unit, in cents.

    • customs_description string

      Description for customs, if different.

    • hs_code string

      Harmonized System code.

    • origin_country string

      Two-letter code of the country where the item was made.

    • sku string

      Your product code.

  • length • Required number

    Length, in dimension_unit.

  • weight • Required number

    Weight of the box with its contents, in weight_unit.

  • weight_unit • Required string

    lb or kg.

  • width • Required number

    Width, in dimension_unit.

  • box_id uuid

    A standard box from GET /v1/package-boxes, if one was used.

  • name string
  • preset_id uuid

    A saved box from GET /v1/package-presets, if one was used.

• reference_number string

  Your reference, e.g. an order number. Printed on the label where the carrier allows.

• ship_date date

  Day the parcel will be handed to the carrier (YYYY-MM-DD). Leave out for today; up to 7 days ahead.

• signature_option string

  Signature on delivery: none, required or adult. Carriers charge extra for a signature.

Response in data

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• email_notifications • Required boolean

  Email tracking updates to the recipient.

• from • Required string

  Ship-from address.

• id • Required uuid
• label_size • Required string

  thermal (4×6 in) or standard (8.5×11 in). Defaults to the account's shipping preference.

• packages • Required string

  One entry per box.

• step • Required string
• to • Required string

  Ship-to address.

• updated_at • Required timestamp

  When it last changed (ISO 8601, UTC).

• customs_declaration_id uuid

  A customs declaration from POST /v1/customs/declarations. Needed for shipments that cross a border.

• delivery_instructions string

  Instructions for the driver.

• discount_code string

  A discount code to apply.

• expires_at timestamp
• processed_at timestamp
• reference_number string

  Your reference, e.g. an order number. Printed on the label where the carrier allows.

• selected_amount_cents integer
• selected_carrier string
• selected_currency string
• selected_service_code string
• selected_service_name string
• ship_date date

  Day the parcel will be handed to the carrier (YYYY-MM-DD). Leave out for today; up to 7 days ahead.

• shipment_id uuid
• signature_option string

  Signature on delivery: none, required or adult. Carriers charge extra for a signature.

Get a draft

GET /v1/shipments/draft/{id}

One draft: addresses, packages, add-ons and the selected rate, if any.

Path parameters

• id • Required string

Response in data

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• email_notifications • Required boolean

  Email tracking updates to the recipient.

• from • Required string

  Ship-from address.

• id • Required uuid
• label_size • Required string

  thermal (4×6 in) or standard (8.5×11 in). Defaults to the account's shipping preference.

• packages • Required string

  One entry per box.

• step • Required string
• to • Required string

  Ship-to address.

• updated_at • Required timestamp

  When it last changed (ISO 8601, UTC).

• customs_declaration_id uuid

  A customs declaration from POST /v1/customs/declarations. Needed for shipments that cross a border.

• delivery_instructions string

  Instructions for the driver.

• discount_code string

  A discount code to apply.

• expires_at timestamp
• processed_at timestamp
• reference_number string

  Your reference, e.g. an order number. Printed on the label where the carrier allows.

• selected_amount_cents integer
• selected_carrier string
• selected_currency string
• selected_service_code string
• selected_service_name string
• ship_date date

  Day the parcel will be handed to the carrier (YYYY-MM-DD). Leave out for today; up to 7 days ahead.

• shipment_id uuid
• signature_option string

  Signature on delivery: none, required or adult. Carriers charge extra for a signature.

Update a draft

PATCH /v1/shipments/draft/{id}

Changes a draft. Fields you leave out stay as they are; null clears a field that can be cleared. To choose a rate, send the selected_* fields and the quote_id from POST /v1/rates.

Path parameters

• id • Required string

Request body

• customs_declaration_id uuid

  A customs declaration from POST /v1/customs/declarations. Needed for shipments that cross a border.

• delivery_instructions string

  Instructions for the driver.

• discount_code string

  A discount code to apply.

• email_notifications boolean

  Email tracking updates to the recipient.

• from object

  Ship-from address.

  Fields · 11

  • city • Required string

    City.

  • country • Required string

    Two-letter country code, e.g. CA, US.

  • name • Required string
  • postal_code • Required string

    Postal or ZIP code.

  • state • Required string

    Province or state code, e.g. ON, BC, NY.

  • street • Required string

    Street address.

  • company string

    Company name.

  • email string

    Email address.

  • is_residential boolean

    True for a home address. Some carriers charge more for residential delivery.

  • line2 string

    Apartment, suite or unit.

  • phone string

    Phone number. Carriers need one for the recipient on most international and express services.

• label_size string

  thermal (4×6 in) or standard (8.5×11 in). Defaults to the account's shipping preference.

• packages array of objects

  One entry per box.

  Each item · 10

  • dimension_unit • Required string

    in or cm.

  • height • Required number

    Height, in dimension_unit.

  • items • Required array of objects

    What is in this box (optional for domestic shipments).

    Each item · 8

    • currency • Required string

      Three-letter currency code, e.g. CAD.

    • description • Required string

      What the item is.

    • quantity • Required integer

      How many.

    • unit_value_cents • Required integer

      Value of one unit, in cents.

    • customs_description string

      Description for customs, if different.

    • hs_code string

      Harmonized System code.

    • origin_country string

      Two-letter code of the country where the item was made.

    • sku string

      Your product code.

  • length • Required number

    Length, in dimension_unit.

  • weight • Required number

    Weight of the box with its contents, in weight_unit.

  • weight_unit • Required string

    lb or kg.

  • width • Required number

    Width, in dimension_unit.

  • box_id uuid

    A standard box from GET /v1/package-boxes, if one was used.

  • name string
  • preset_id uuid

    A saved box from GET /v1/package-presets, if one was used.

• quote_id uuid

  The quote_id from the POST /v1/rates response the chosen rate came from.

• reference_number string

  Your reference, e.g. an order number. Printed on the label where the carrier allows.

• selected_amount_cents integer

  The chosen rate's amount_cents.

• selected_carrier string

  The chosen rate's carrier.

• selected_currency string

  The chosen rate's currency.

• selected_duties_cents integer

  The chosen rate's duties_cents, if any.

• selected_service_code string

  The chosen rate's service_code.

• selected_service_name string

  The chosen rate's service_name.

• ship_date date

  Day the parcel will be handed to the carrier (YYYY-MM-DD). Leave out for today; up to 7 days ahead.

• signature_option string

  Signature on delivery: none, required or adult. Carriers charge extra for a signature.

• to object

  Ship-to address.

  Fields · 11

  • city • Required string

    City.

  • country • Required string

    Two-letter country code, e.g. CA, US.

  • name • Required string
  • postal_code • Required string

    Postal or ZIP code.

  • state • Required string

    Province or state code, e.g. ON, BC, NY.

  • street • Required string

    Street address.

  • company string

    Company name.

  • email string

    Email address.

  • is_residential boolean

    True for a home address. Some carriers charge more for residential delivery.

  • line2 string

    Apartment, suite or unit.

  • phone string

    Phone number. Carriers need one for the recipient on most international and express services.

Response in data

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• email_notifications • Required boolean

  Email tracking updates to the recipient.

• from • Required string

  Ship-from address.

• id • Required uuid
• label_size • Required string

  thermal (4×6 in) or standard (8.5×11 in). Defaults to the account's shipping preference.

• packages • Required string

  One entry per box.

• step • Required string
• to • Required string

  Ship-to address.

• updated_at • Required timestamp

  When it last changed (ISO 8601, UTC).

• customs_declaration_id uuid

  A customs declaration from POST /v1/customs/declarations. Needed for shipments that cross a border.

• delivery_instructions string

  Instructions for the driver.

• discount_code string

  A discount code to apply.

• expires_at timestamp
• processed_at timestamp
• reference_number string

  Your reference, e.g. an order number. Printed on the label where the carrier allows.

• selected_amount_cents integer
• selected_carrier string
• selected_currency string
• selected_service_code string
• selected_service_name string
• ship_date date

  Day the parcel will be handed to the carrier (YYYY-MM-DD). Leave out for today; up to 7 days ahead.

• shipment_id uuid
• signature_option string

  Signature on delivery: none, required or adult. Carriers charge extra for a signature.

Delete a draft

DELETE /v1/shipments/draft/{id}

Deletes an unpurchased draft.

Path parameters

• id • Required string

Response in data

See the example on the right.

Buy a draft

POST /v1/shipments/draft/{id}/process

Buys the label for the rate selected on the draft and charges the wallet. The draft becomes a shipment.

Confirm with the account owner before calling it.

Path parameters

• id • Required string

Response in data

• archived • Required boolean

  true to archive (the default), false to bring it back.

• base_rate_cents • Required integer

  Label price before discount and tax, in cents.

• carrier • Required string

  Carrier code, as returned with each rate.

• carrier_display_name • Required string

  Carrier name to show to people.

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• currency • Required string

  Three-letter currency code, e.g. CAD.

• discount_cents • Required integer

  Discount applied, in cents.

• duties_cents • Required integer

  Destination duties and taxes prepaid with this label (DDP), when offered.

• email_notifications • Required boolean

  Email tracking updates to the recipient.

• final_rate_cents • Required integer

  What was charged: price − discount + tax + prepaid duties, in cents.

• from_address • Required any
• has_customs_invoice • Required boolean
• id • Required uuid
• is_return • Required boolean
• label_size • Required string

  thermal (4×6 in) or standard (8.5×11 in). Defaults to the account's shipping preference.

• order_number • Required string
• packages • Required any

  One entry per box.

• refund_pending • Required boolean
• refund_withheld • Required boolean
• refunded_cents • Required integer
• service • Required string
• status • Required string
• tax_cents • Required integer

  Sales tax, in cents.

• tax_rate_bps • Required integer
• to_address • Required any
• tracking_available • Required boolean

  False for a service without tracking.

• updated_at • Required timestamp

  When it last changed (ISO 8601, UTC).

• batch object
  Fields · 3

  • batch_number • Required string
  • id • Required uuid
  • name • Required string
• cancelled_at timestamp
• created_by_email string
• created_by_name string
• delivery_instructions string

  Instructions for the driver.

• paid_at timestamp
• reference_number string

  Your reference, e.g. an order number. Printed on the label where the carrier allows.

• refund_held_until timestamp
• return_of uuid
• ship_date date

  Day the parcel will be handed to the carrier (YYYY-MM-DD). Leave out for today; up to 7 days ahead.

• signature_option string

  Signature on delivery: none, required or adult. Carriers charge extra for a signature.

• tax_jurisdiction string
• tracking_number string

  The carrier's tracking number.

• wallet_transaction_id uuid

List drafts

GET /v1/shipments/drafts

Unpurchased shipments, newest first: saved forms and orders imported from stores or files.

Query parameters

• limit integer

  Most results to return.

• offset integer

  Results to skip, for paging.

• batch_id string

  Only drafts for this batch, or none for drafts without a batch.

Response in data

• batches • Required array of objects
  Each item · 4

  • count • Required integer
  • batch_id uuid

    A batch from GET /v1/batches.

  • name string
  • status string
• items • Required array of objects
  Each item · 17

  • created_at • Required timestamp

    When it was created (ISO 8601, UTC).

  • id • Required uuid
  • package_count • Required integer
  • step • Required string
  • updated_at • Required timestamp

    When it last changed (ISO 8601, UTC).

  • batch_id uuid

    A batch from GET /v1/batches.

  • batch_name string
  • batch_status string
  • expires_at timestamp
  • selected_amount_cents integer
  • selected_carrier string
  • selected_currency string
  • selected_service_name string
  • shipment_id uuid
  • to_city string
  • to_country string

    Ship-to country code.

  • to_name string
• total • Required integer