QUICKSTART
API Quick Start
Authentication
SignString
Versioning
Rate Limit
Body Envelope
Request Errors
Common Scenarios
Tracking
Shipping
Returns
CHANGELOG
Changelog
Migration Guide
REFERENCE
API Overview
Orders
Create an order
post
List Orders
get
Get an order
get
Update an order
patch
Products
Create a product
post
Get a product
get
Update a product
patch
Stores
Create a store
post
List Stores
get
Get a store
get
Update a store
patch
Model
Envelope
Meta
v1
Error
v1
Pagination
v1
Primitive
Address
v1
Customer
v1
Money
v1
Shipment
v1
Weight
v1
StoreAddress
v1
Resource
Order
v1
OrderItem
v1
Product
v1
Store
v1
Support
Contact Support

Order

id
string
read-only

Unique identifier generated by AfterShip.

<= 32 characters
Example:
0ecb8ff7efa84d7d8f763ed7b89851c8
source_id
string
required

A unique identifier for the order in your system.

<= 32 characters
Example:
5187092316403
store
object

Indicate which store the order belongs to.

id
string
read-only

Unique identifier generated by AfterShip. Related to the Stores API, you can use this id to get store details using GET /stores/{id} API.

Example:
0ecb8ff7efa84d7d8f763ed7b21851d1
name
string

The order name. Default is the same value as number.

<= 256 characters
Example:
#1086
number
string
required

The order number.

<= 64 characters
Example:
1086
currency
string
required

The curreny of order. ISO 4217 Currency Codes.

Example:
HKD
Match pattern:
^[A-Z]{3}$
status
string
required

The status of this order.

Allowed values:
openclosedcanceled
financial_status
string

The status of payments associated with the order.

Allowed values:
unpaidpartially_paidpaidpartially_refundedrefunded
fulfillment_status
string

The status of fulfillment associated with the order.

Allowed values:
unfulfilledpartially_fulfilledfulfilled
order_total
string
required

The total price of the order.

<= 100 characters
Example:
97
shipping_total
string

The total shipping fee applied to the price of the order.

<= 100 characters
Example:
5
tax_total
string

The sum of all the taxes applied to the order.

<= 100 characters
Example:
10
discount_total
string

The total discount applied to the order. Its value should be equal to the sum of all item discounts.

<= 100 characters
Example:
1
subtotal
string

The price of the order after discounts but before shipping and taxes.

<= 100 characters
Example:
90
items
array[OrderItem]

Items of order.

<= 100 items
source_id
string
required

A unique identifier for the line item in your system. You should pass it when create order. Please note:

  1. This is NOT the product.source_id of products API.
  2. This source_id should be the same as order.shipments.items.source_order_item_id.
<= 32 characters
Example:
13097711141107
sku
string

The item's SKU (stock keeping unit).

<= 256 characters
Example:
yellow
quantity
integer
required

The number of items that have been purchased.

unit_weight
Weight

The item's weight.

Example:
{"unit":"kg","value":10}
unit_price
string

The price of the item before discounts and taxes have been applied.
Please note that the item total price needs to meet the following formula:
item total price paid = unit_price*quantity - discount + tax

<= 100 characters
Example:
8
discount
string

The total amount of the discount allocated to the line item. Including the discount applied only on this item and the allocated discount for the order level discount.

<= 100 characters
Example:
1
tax
string

The total amount of the tax allocated to the line item.

<= 100 characters
Example:
1
fulfillable_quantity
integer

Deprecated, do not use. This field is no longer supported and should not be included in API requests. Total items available to fulfill.

source_product_id
string

The ID of the product that the line item belongs to. It Please note:

  1. It should be the same as the product.source_id of products API.
<= 32 characters
Example:
8021450916083
source_variant_id
string

The ID of the product variant. Default is the same value as source_product_id. Please note:

  1. It should be the same as the product.variants.source_id of products API.
<= 32 characters
Example:
43768285298931
title
string
required

The title of the product variant.

<= 1024 characters
Example:
good hair
hs_code
string

Harmonized System (HS) Codes.

<= 256 characters
Example:
sw343
origin_country_region
string

The origin country of this product.

Example:
USA
Match pattern:
^[A-Z]{3}$
image_urls
array[string]

Image urls of this variant.

<= 100 items
product_tags
array[string]

Product tags of this variant.

product_categories
array[string]

Product categories of this variant.

returnable_quantity
integer
Example:
3
shipments
array[Shipment]

order shipments.

<= 100 items
tracking_number
string

Tracking number.

<= 256 characters
Example:
2591043243
slug
string

Unique code of the courier. Get couriers here: https://www.aftership.com/couriers.

<= 256 characters
Example:
dhl
additional_fields
object
items
array[object]

A list of line item objects, each containing information about an item in the shipment.

<= 100 items
source_id
string
required

A unique identifier for the shipment in your system.

<= 32 characters
Example:
12
source_created_at
string

The date and time (ISO 8601 format) when shipment was created.

Example:
2021-04-15T20:02:09Z
service_type
string

The type of logistics service selected for this shipment, e.g. FedEx, SmartPost.

Example:
FedEx
ship_from_address
Address
Example:
{"source_id":"1","description":"My Home Address","company":"aftership","first_name":"teddy","last_name":"chan","email":"[email protected]","address_line_1":"address2","address_line_2":"1233","address_line_3":null,"city":"HongKong","state":"HKG","country_region":"HKG","postal_code":"12323","phone":"+8613265883816","type":null,"tax_number":null}
custom_fields
object

Custom fields that accept an object with string field.Show all...

note
string

An optional note that a shop owner can attach to the order.

<= 5000 characters
Example:
created by AfterShip
source_created_at
string

The date and time (ISO 8601 format) when an order was created.

Example:
2021-04-15T20:02:09Z
source_updated_at
string

The date and time (ISO 8601 format) when an order was updated.

Example:
2021-04-16T20:02:09Z
created_at
string

The date and time (ISO 8601 format) when an order was created in AfterShip.

Example:
2021-04-15T20:02:09Z
updated_at
string

The date and time (ISO 8601 format) when an order was updated in AfterShip.

Example:
2021-04-16T20:02:09Z
customer
Customer
Example:
{"source_id":"5127837778090","first_name":"teddy","last_name":"chan","emails":["[email protected]"],"locale":"en-US","phones":["+8613265883816"]}
source_id
string

A unique identifier for the customer.

<= 32 characters
first_name
string

The customer's first name.

<= 256 characters
last_name
string

The customer's last name.

<= 256 characters
emails
array[string]

The customer's email.

<= 100 items
phones
array[string]

The customer's phone number.

<= 100 items
locale
string

The language code of the customer, eg: en-US.

<= 128 characters
shipping_address
Address
Example:
{"source_id":"1","description":"My Home Address","company":"aftership","first_name":"teddy","last_name":"chan","email":"[email protected]","address_line_1":"address2","address_line_2":"1233","address_line_3":null,"city":"HongKong","state":"HKG","country_region":"HKG","postal_code":"12323","phone":"+8613265883816","type":null,"tax_number":null}
billing_address
Address
Example:
{"source_id":"1","description":"My Home Address","company":"aftership","first_name":"teddy","last_name":"chan","email":"[email protected]","address_line_1":"address2","address_line_2":"1233","address_line_3":null,"city":"HongKong","state":"HKG","country_region":"HKG","postal_code":"12323","phone":"+8613265883816","type":null,"tax_number":null}
tags
array[string]

Tags attached to the order.

<= 100 items
shipping_method
string

The name of the shipping method.

<= 256 characters
Example:
standard shipping
Example
{
  "id": "0ecb8ff7efa84d7d8f763ed7b89851c8",
  "source_id": "5187092316403",
  "store": {
    "id": "0ecb8ff7efa84d7d8f763ed7b21851d1"
  },
  "name": "#1086",
  "number": "1086",
  "currency": "HKD",
  "status": "open",
  "financial_status": "unpaid",
  "fulfillment_status": "unfulfilled",
  "order_total": "97",
  "shipping_total": "5",
  "tax_total": "10",
  "discount_total": "1",
  "subtotal": "90",
  "items": [
    {
      "source_id": "13097711141107",
      "sku": "yellow",
      "quantity": 0,
      "unit_weight": {
        "unit": "kg",
        "value": 10
      },
      "unit_price": "8",
      "discount": "1",
      "tax": "1",
      "fulfillable_quantity": 0,
      "source_product_id": "8021450916083",
      "source_variant_id": "43768285298931",
      "title": "good hair",
      "hs_code": "sw343",
      "origin_country_region": "UK",
      "image_urls": [
        "https://www.healthline.com/health/dull-hair"
      ],
      "product_categories": [
        "makeup"
      ],
      "product_tags": [
        "for good girl"
      ]
    }
  ],
  "shipments": [
    {
      "tracking_number": "2591043243",
      "slug": "dhl",
      "additional_fields": {
        "account_number": "876994760",
        "key": "38784963",
        "postal_code": "058050",
        "ship_date": "20191126",
        "state": "NewYork",
        "origin_country_region": "USA",
        "destination_country_region": "UK"
      },
      "items": [
        {
          "source_order_item_id": "44",
          "quantity": 1
        }
      ],
      "source_id": "12",
      "source_created_at": "2021-04-15T20:02:09Z",
      "service_type": "FedEx",
      "ship_from_address": {
        "source_id": "1",
        "description": "My Home Address",
        "company": "aftership",
        "first_name": "teddy",
        "last_name": "chan",
        "email": "[email protected]",
        "address_line_1": "address2",
        "address_line_2": "1233",
        "address_line_3": null,
        "city": "HongKong",
        "state": "HKG",
        "country_region": "HKG",
        "postal_code": "12323",
        "phone": "+8613265883816",
        "type": null,
        "tax_number": null
      },
      "custom_fields": {
        "product_name": "iPhone Case",
        "product_price": "USD19.99"
      }
    }
  ],
  "note": "created by AfterShip",
  "source_created_at": "2021-04-15T20:02:09Z",
  "source_updated_at": "2021-04-16T20:02:09Z",
  "created_at": "2021-04-15T20:02:09Z",
  "updated_at": "2021-04-16T20:02:09Z",
  "customer": {
    "source_id": "5127837778090",
    "first_name": "teddy",
    "last_name": "chan",
    "emails": [
      "[email protected]"
    ],
    "locale": "en-US",
    "phones": [
      "+8613265883816"
    ]
  },
  "shipping_address": {
    "source_id": "1",
    "description": "My Home Address",
    "company": "aftership",
    "first_name": "teddy",
    "last_name": "chan",
    "email": "[email protected]",
    "address_line_1": "address2",
    "address_line_2": "1233",
    "address_line_3": null,
    "city": "HongKong",
    "state": "HKG",
    "country_region": "HKG",
    "postal_code": "12323",
    "phone": "+8613265883816",
    "type": null,
    "tax_number": null
  },
  "billing_address": {
    "source_id": "1",
    "description": "My Home Address",
    "company": "aftership",
    "first_name": "teddy",
    "last_name": "chan",
    "email": "[email protected]",
    "address_line_1": "address2",
    "address_line_2": "1233",
    "address_line_3": null,
    "city": "HongKong",
    "state": "HKG",
    "country_region": "HKG",
    "postal_code": "12323",
    "phone": "+8613265883816",
    "type": null,
    "tax_number": null
  },
  "tags": [
    "this is a tag"
  ],
  "shipping_method": "standard shipping"
}