Quick Start

Authentication

Sign String

OAuth

Overview

Getting Started

Scope List

Rate Limit

Body Envelope

Request Errors

Changelog

Reference

API Overview v3

Rates

• Get rates (GET)
• Calculate rates (POST)
• Get a rate (GET)

Labels

• Get labels (GET)
• Create a label (POST)
• Get a label (GET)

Manifests

• Get manifests (GET)
• Create a manifest (POST)
• Get a manifest (GET)

Couriers

• Get all couriers (GET)

Cancel Labels

• Get the cancelled labels (GET)
• Cancel a label (POST)
• Get a cancelled label (GET)

Pickups

• Get pickups (GET)
• Create a pickup (POST)
• Get a pickup (GET)

Cancel Pickups

• Get the cancelled pickups (GET)
• Cancel a pickup (POST)
• Get a cancelled pickup (GET)

Shipper Accounts

• Get shipper accounts (GET)
• Create a shipper account (POST)
• Get a shipper account (GET)
• Delete a shipper account (DELETE)
• Update a shipper account's information (PUT)
• Update a shipper account's credentials (PATCH)
• Update a shipper account's settings (PATCH)

Specific Shipper Accounts

• Create a FedEx shipper account (POST)
• Update a FedEx shipper account (POST)

Address Validations (Beta)

• Create an address validation (POST)

Locations

• Get locations (GET)

Model

Envelope

• Meta v3
• Error v3

Primitive

• Billing v3
• Customs v3
• Shipment v3
• Address v3
• Parcel v3
• Item v3
• Courier v3
• Reference v3
• Money v3
• PaymentMethodAccount v3
• Dimension v3
• Weight v3
• Volume v3
• Aes v3
• NoEei v3

Resource

• Rate v3
• RateRecord v3
• Label v3
• Manifest v3
• ShipperAccount v3
• CancelLabel v3
• AddressValidation (Beta) v3
• Location v3
• Pickup v3
• CancelPickup v3

Carrier Guide

• Supported Carriers

ENUM

• Shipper Accounts Credentials
• Service Types and Service Options List
• All Service Options

Webhook

• Webhook Overview
• Webhook Specifications
• Webhook Signature
• Webhook Outgoing IPs

SDK

• Java SDK
• Node.js SDK

Open Source

• phone
• email-verifier

Support

• Contact Support

Create a label

POST

Endpoint

https://sandbox-api.aftership.com/postmen/v3/labels

Create a label.
This array contains service_options object. Please refer to all service options and service options list for details.
This array contains reference data. Please refer to reference object for label object details.

Request

• Security: API Key

Headers

• Content-Type: string (required)
  • Default: application/json

Body

Create a label object.

• billing: Billing object: the description of billing information
  • paid_by: string (required)
    • Allowed values: shipper, third_party, recipient
  • method: PaymentMethodAccount
  • customs: Customs object: the description of customs information
  • purpose: string (required)
    • Allowed values: gift, merchandise, personal, sample, return, repair, non-merchandise
  • terms_of_trade: string
  • eei: AESNOEEI
  • importer_address: Address
  • broker_address: Address
  • additional_charges: array[object]
    • This array contains additional_charges object. Additional charge to be added to the commercial invoice of this shipment. Only applies to FedEx, DHL Express, UPS currently.
    • <= 3 items
  • return_shipment: boolean (set to false if not provided)
  • is_document: boolean (If the shipment is document type. Set to false if not provided)
  • service_type: string
  • paper_size: string
  • shipper_account: object
    • id: string
    • references: array[string]
  • shipment: Shipment object: the description of shipment information
    • refer to shipment object.
  • tax_total: Money
  • ship_from: Address (required)
    • Address object: the description of address information
  • ship_to: Address (required)
    • Address object: the description of address information
  • parcels: array[Parcel] (required)
    • Parcels of shipment
  • return_to: Address
  • delivery_instructions: string
  • invoice: Invoice or null
    • Invoice object: the description of invoice type, commercial invoice will be generated if field is present in the request body
  • date: string (required)
    • Invoice date in YYYY-MM-DD
  • number: string
  • type: string
    • Allowed values: commercial, proforma
  • number_of_copies: integer (>= 1, <= 4)
  • signature_name: string
  • declaration_statement: string
  • service_options: array[object]
    • This array contains service_options object. Please refer to all service options and service types and service options list for details.
  • file_type: string
    • Allowed values: pdf, zpl
  • ship_date: string
    • Ship Date in YYYY-MM-DD, if not provided, will be today of the shipper account timezone
  • order_number: string
    • A user-defined order number used to identify an order.
  • order_id: string
    • Unique identification of the order.
  • custom_fields: object
    • Custom fields that accept an object with string field.
  • files: InputFiles
    • Files object: additional shipping documents to upload with label generation. Only applies to FedEx, DHL Express currently.
  • certificate_of_origin: object
  • commercial_invoice: object
  • customs_declaration: object
  • print_options: object
    • qr_code: object
      • Whether to return the qr_code when creating a label
      • Supported slug: arvato, canada-post, dpd-uk, evri, vesyl, usps, poste-italiane, pitney-bowes, dpd-nl, dpd-prt, mondialrelay
      • automatic: boolean (When set to true, automation rules configured for the organization will be applied to this label request. Enterprise only.)

Responses

• 200 OK

Body

• meta: Meta data object.
• data: Label object: the description of label object
  • This array contains service_options object. Please refer to all service options and service options list for details.
  • This array contains reference data. Please refer to reference object for label object details.
  • id: string
  • status: string
    • Allowed values: creating, created, cancelling, cancelled, manifesting, manifested, failed
  • ship_date: string
  • tracking_numbers: array[string]
  • carrier_references: array[object]
  • files: Files object: the description of 6 different file objects(label, qr_code, invoice, customs_declaration, packing_slip, manifest)
  • rate: Rate object: the description of rate information
  • created_at: string
    • A formatted date.
  • updated_at: string
    • A formatted date.
  • references: array[string] or null
  • shipper_account: Reference object: the description of reference information
  • service_type: string
  • order_number: string
  • service_options: array[object]
  • order_id: string
  • custom_fields: object
  • carrier_redirect_link: string or null

Auth

• as-api-key:
  • Parameters
  • Content-Type*:

Request Sample: Shell / cURL

curl --request POST \
  --url https://sandbox-api.aftership.com/postmen/v3/labels \
  --header 'Content-Type: application/json' \
  --header 'as-api-key: ' \
  --data '{
    "return_shipment": false,
    "is_document": false,
    "service_type": "ups_ground",
    "paper_size": "4x6",
    "shipper_account": {
        "id": "3ba41ff5-59a7-4ff0-8333-64a4375c7f21"
    },
    "references": ["refernce1"],
    "shipment": {
        "ship_from": {
            "contact_name": "AfterShip Shipping",
            "company_name": "AfterShip Shipping",
            "street1": "230 W 200 S LBBY",
            "city": "Salt Lake City",
            "state": "UT",
            "postal_code": "84101",
            "country": "USA",
            "phone": "19835553752",
            "email": "test@test.com"
        },
        "ship_to": {
            "contact_name": "AfterShip Shipping",
            "company_name": "AfterShip Shipping",
            "street1": "230 W 200 S LBBY",
            "city": "Salt Lake City",
            "state": "UT",
            "postal_code": "84101",
            "country": "USA",
            "phone": "19835553752",
            "email": "test@test.com"
        },
        "parcels": [
            {
                "box_type": "custom",
                "dimension": {
                    "width": 10,
                    "height": 10,
                    "depth": 10,
                    "unit": "cm"
                },
                "items": [
                    {
                        "description": "Food Bar",
                        "quantity": 1,
                        "price": {
                            "currency": "USD",
                            "amount": 100
                        },
                        "item_id": "1234567",
                        "origin_country": "CHN",
                        "weight": {
                            "unit": "kg",
                            "value": 1
                        },
                        "sku": "imac2014",
                        "hs_code": "100630",
                        "return_reason": "too big"
                    }
                ],
                "description": "Food XS",
                "weight": {
                    "unit": "kg",
                    "value": 1
                }
            }
        ]
    },
    "custom_fields": {
        "ship_code": "01"
    },
    "print_options": {
        "qr_code": {
            "enabled": true
        }
    }
}'

Response Example

{
  "meta": {
    "code": 200,
    "message": "OK",
    "details": []
  },
  "data": {
    "id": "3318b97b-150f-4205-840d-a6d966b9e0ea",
    "status": "created",
    "tracking_numbers": ["3884930103"],
    "files": {
      "label": {
        "paper_size": "4x8",
        "url": "https://sandbox-download.postmen.com/label/2015-11-27/00000000-0000-0000-0000-000000000000-1441785264309885.pdf",
        "file_type": "pdf"
      },
      "invoice": null,
      "customs_declaration": null,
      "manifest": null
    },
    "rate": {
      "charge_weight": {
        "value": 3.307,
        "unit": "lb"
      },
      "total_charge": {
        "amount": 0,
        "currency": "USD"
      },
      "shipper_account": {
        "id": "00000000-0000-0000-0000-000000000000",
        "slug": "dhl",
        "description": "DHL Sandbox"
      },
      "service_type": "dhl_express_0900",
      "service_name": "DHL Express 0900",
      "pickup_deadline": null,
      "booking_cut_off": null,
      "delivery_date": null,
      "transit_time": null,
      "detailed_charges": [],
      "error_message": null,
      "info_message": null
    },
    "created_at": "2022-05-09T07:54:13.024Z",
    "updated_at": "2022-09-09T07:54:24.569Z",
    "ship_date": "2022-09-09"
  },
  "custom_fields": {
    "ship_code": "01"
  }
}