API Quick Start

This quickstart guide intends to walk you through the common scenario to help you know how to use the AfterShip Commerce API.

Request demo

---

1. What is Commerce API?

Commerce API is a collection of eCommerce functionality exposed via API. It provides access to core capabilities that are commonly used in Stores, Products, Orders, and other eCommerce activities.

2. API Endpoint

All endpoints are only accessible via HTTPS.

3. Common scenarios

Scenario 1. Returns Quick Start

If you want to quickly use the basic functions of Returns, please follow these steps:

1. Generate an API Key
2. Complete Returns Onboarding
3. Import Orders

preparing...

Once you have successfully imported the orders according to the above example, the following features of Returns can be used:

1. Accept return request in Returns Page
Customers can use their number/name + customer.emails on the Returns Page to find their order, then select return items, return reason, return resolution, shipping, and finally submit a return request.

2. Returns window - Order date
You can configure returns window based on source_created_at, and any return requests exceeding this window will be automatically blocked.

3. Blocklist - Customer
You can configure blocklist based on customer.emails to block return requests.

4. Allowlist - Order
You can configure allowlist based on name, making exceptions for specific orders so that customers can raise return requests.

5. Allowlist - Customer
You can configure allowlist based on customer.emails, making exceptions for specific customers so that they can raise return requests.

Scenario 2. Returns Advanced Features

If you want to use more features of Returns, you can import order according to the following example:

preparing...

Once you have successfully imported the orders according to the above example, the following features of Returns can be used:

1. Returns window - Fulfillment date
You can configure returns window based on shipments[*].source_created_at, and any return requests exceeding this window will be automatically blocked.

2. Discounted items
You can enable Do not accept discounted items, and order with items[*].discount greater than 0 will be automatically blocked.

3. Blocklist - Product type
You can configure blocklist based on items[*].product_categories to block return requests.

4. Blocklist - Product tag
You can configure blocklist based on items[*].product_tags to block return requests.

5. Allowlist - Product type
You can configure allowlist based on items[*].product_categories, making exceptions for specific product types so that customers can raise return requests.

6. Allowlist - Product tag
You can configure allowlist based on items[*].product_tags, making exceptions for specific product tags so that customers can raise return requests.

7. Replace for another variant
You can provide Replace with the same item resolution to customer, but you need to import store and the corresponding products according to the following example:

Scenario 3. Shipping Quick Start

If you want to quickly use the basic functions of Shipping, please follow these steps:

1. Generate an API Key
2. Complete Shipping Onboarding
3. Import Orders

preparing...

Once you have successfully imported the orders according to the above example, you can manage the imported orders and create labels in Shipping. Please note that some carriers may require additional fields to create labels, so if you find that imported orders can not create labels, please contact us for assistance.

Scenario 4. Tracking Quick Start

To use the Tracking app through the Commerce API, please follow the instructions below to import the data.

1. Generate an API Key for Commerce API

To get started, you need to generate an API Key. You can do this by visiting this link.

2. Activate Commerce API by contact support

Please contact the support team or customer manager(if you have one) to activate your Commerce API.

3. Import data based on the features you wish to use

Basically, you can use the provided curl command below to import orders. Make sure to replace "your API key" and "your store ID" in the command with your actual API Key and Store ID.
Once you have successfully imported orders, you can view the shipments in the Tracking app admin page.

All fields in this example are mandatory, regardless of the features you intend to use.

preparing...

The above example simply ensures that you can view the shipments on the Tracking admin page. Below, you will find the description and the key fields that each feature requires.

• Custom EDD
  The Custom estimated delivery date is used in cases where you already have a mechanism to calculate the estimated delivery date based on the shipping type, carrier, and destination.
  The general formula of computing custom EDD for the selected industry type is:
  Order date + Order cutoff & processing time + Transit time

  Formula Filed Name	Description
  Order date	The creation time of the order needs to be passed through the "source_created_at" field in the order payload.
  Order cutoff & processing time	The processing time for an order is configured on the Tracking's admin page.
  Transit time	The estimated shipping time is configured on the Tracking's admin page.

• Email Notifications
  Tracking allows you to send email notifications for different delivery statuses. With swift email notifications, you can keep your customers updated about their order status.
  To use the email notification feature, please add the valid customer email addresses (customer.emails) to the order payload.
  If you want to configure an email workflow based on the status of an order, make sure you provide the following three fields: status, fulfillment_status, and source_created_at.
  If you want to set up an email workflow using workflow trigger filters, you can incorporate the corresponding fields mentioned in the reference table below:

  Trigger Filter Name	Commerce API Field Name
  Order number	number
  Order status	status
  Product type	items[*].product_categories
  Destination country/region	shipping_address.country_region
  Slug	shipments[*].slug
  Custom fields	shipments[*].custom_fields
  Source	When importing through the Commerce API, you can choose 'automizely-private'.

• SMS Notifications
  To use the sms notification feature, please add the valid customer phone numbers (customer.phones) to the order payload.

• Segmentation
  To use the Segmentation feature, you can incorporate the corresponding fields mentioned in the reference table below:

  Segmentation Condition Field Name	Commerce API Field Name
  Order -> Total billing amount	order_total
  Order -> Order tag	tags
  Order -> Order number	number
  Product -> Product SKU	items[*].sku
  Product -> Product type	items[*].product_categories
  Product -> Product tag	items[*].product_tags
  Shipment -> Carrier	shipments[*].slug
  Shipment -> Shipment title	name
  Shipment -> Destination country/region	shipping_address.country_region
  Shipment -> Destination state	shipping_address.state
  Shipment -> Destination postal code	shipping_address.postal_code
  Custom field	shipments[*].custom_fields

• Shipment Items
  If you want to display shipment items in the tracking detail, tracking page, and notifications, please import order data according to the following example:

  preparing...

• Product recommendation
  If you want to use the Product recommendation feature, please import store, order and product data according to the following examples:

• Product documents
  If you want to use the Product documents feature, please import store, order and product data according to the following examples:

  Key field	description
  order.shipments[*].custom_fields.package_count	The total number of packages to be unpacked for this shipment should be entered. For example, if the order requires 2 packages to be unpacked for shipment, please enter 2. Tracking will use this information to determine the last package of the shipment. Once Tracking confirms that the last package has been delivered, the product documents will be sent.

• Notifications - Flow
  To create a custom flow and utilize flow filters related to SHOPPING BEHAVIOR, you can import store, order, and product data following the examples provided below:

  Key field	description
  order.customer.source_id	A unique identifier for the customer. The ID will be used to calculate values related to SHOPPING BEHAVIOR.
  order.financial_status	The financial_status should not be unpaid. Only when financial_status is not equal to 'unpaid', the order will be used to calculate values related to SHOPPING BEHAVIOR.
  order.source_created_at	The creation time of the order used to calculate the number of orders within the relevant time period. Related SHOPPING BEHAVIOR：First order date,Last order date,Number of recent orders.
  order.order_total	Related SHOPPING BEHAVIOR：Total spent,Avg. order value.
  order.items[x].source_product_id	Related SHOPPING BEHAVIOR：Purchased products.
  order.items[x].source_variant_id	Related SHOPPING BEHAVIOR：Purchased products.