BoxC Logistics, Inc. provides a simple and powerful RESTful Application Programming Interface (API) to integrate seamlessly with other applications. All requests use the application/json content type and go over HTTPS. You can use any programming language to interact with the API. There are currently three components to BoxC's API: Shipping, Fulfillment, and Returns.

Shipping

This component gives you the option to integrate with BoxC's international shipping service allowing you to generate labels and tracking numbers on demand.

Process

  1. You will create one or more shipments.
  2. A shipment can have multiple labels, but only one can be uncancelled at any time (cancelled labels are shown in red).
  3. Shipments are assigned to one or more overpacks that you must create. You can assign them while creating or updating the shipment, or by the shipment's uncancelled label in case you want to scan tracking numbers.
  4. Once you've finished creating overpacks and assigning shipments to them, you will need to create a manifest with the selected overpacks. When a manifest is created the shipment information is transmitted to the appropriate parties, and the related shipments and overpacks can no longer be modified.
The graphic below presents a high level view of the shipping process.

Testing

BoxC does provide a way for applications to test their code. The application needs to set the test property to true when creating a shipment. This results in test labels being generated every time for that particular Shipment at no cost to the user. The endpoint remains the same. Shipments cannot update the test property after creation because it is immutable.

Test labels are easily distinguishable from normal labels by their tracking number and the word "Test" written on it. A test label cannot be used for your Shipment because the carrier(s) are unable to process it. Furthermore, you will lose the contents of your shipment if you do send a test label.

Services

BoxC currently provides three shipping services with varying price and transit time based on the entry point and destination. The service can be selected using the Shipments resource. Use the Estimate resource to receive the approximate shipping cost and transit time for each available service.

Shipping Methods

Each Service has one or more shipping methods that can be selected using the corresponding code. By default all services contain a "Standard" shipping_method that has an empty string for its code. The "Standard" method is used by default when creating a shipment. Use the Estimate resource to retrieve the various shipping method codes for a given route. The code may then be used as the shipping_method property in the Shipments resource.

Fulfillment

This component gives you the option to deeply integrate with BoxC's fulfillment solution. BoxC will allocate your inventory to warehouses located worldwide and fulfill your orders on demand.

Process

  1. You will create a BoxC shop or connect a third party shop using the Shops resource.
  2. You will create one or more Products which can each have one or more SKUs.
  3. You will send a number of your products to one or more warehouses by creating Inbound Shipments.
  4. Meanwhile, you can create Orders manually and/or wait for the system to import them from your connected shops. You can make changes to orders as long as it's not being processed by the warehouse.
  5. BoxC will take care of the rest of the workflow. Just keep your inventory stocked and your invoices paid.

Warehouses

These facilities are strategically located around the world to house and maintain product inventory. There are a few fulfillment warehouses with more being added in the future. Use the Warehouses resource to retrieve information about our supported fulfillment warehouses.

Returns

This component allows you to query and reship shipments returned to a BoxC facility as long as you maintain an active subscription to the service. Shipments intended to use service must have a From (Return) address set to a facility operated by BoxC.

Process

  1. You must subscribe to the Returns by BoxC service.
  2. You may then use the Returns resource to query the system for processed returns and verify individual packages for item count or damage.
  3. Depending on the situation you may choose to reship one or more packages at once using the Reshipments resource.

Facilities

Shipments created using BoxC have a return address set to a BoxC facility by default. Shipments returned to this address will be processed if the user has a subscription to the Returns service; otherwise, it will be discarded. The address can be changed by updating their global account settings or on an individual basis.

Connecting

A quick walkthrough on how to get started with BoxC's API including setting up your first application.

Applications

In order to use the API you must have an Application ID and Secret, or use an existing application that is already set up to use the API. Contact Support to create an application and start testing. Users are allowed to own multiple applications. Application management requires users to have a BoxC account. You can create an account if you don't already have one.

Endpoint

The API endpoint for both production and test resources is https://api.boxc.com/v1/. The URI includes the major version of the API that you wish to use. In this case, it's v1 for Version 1.x.

Authentication

Applications use the OAuth resource to retrieve an access token for a user that lasts indefinitely rather than sending account credentials each request. The user can revoke their access token at any time. It's up to the application to store access tokens securely, and to send the correct access token representative of that user in each request header.

Users that authorize an application for the first time will need to contact BoxC to set up their Billing account. They won't be able to create production labels until they add funds to their balance.

Responses

If there is an error the server will return an error code with a corresponding message describing the error. There is a table of errors that explains what each error means in more detail. If you encounter an error, take action immediately rather than resending the same request. If you receive a 500 Internal Server Error it means something went wrong on BoxC's end, and we should be contacted.

An output resulting from an error includes four properties: status, code, http_status, and message. See the example below.

{
    "status": "error",
    "code": 1200,
    "http_status": 400,
    "message": "Label could not be created"
}

Addresses

There are several addresses involved with the shipping process that are described below to help the user differentiate between them. It's important to understand all of them because any mistakes may cause shipments to be delayed or never reach the recipient.

Company (Consignor) Address

The company address is required before creating shipments (see Users). This is the same thing as the consignor, and it will be used by default if the user does not provide the consignor property for an individual shipment. If a user is shipping packages for multiple people but does not want their own company address listed as the consignor for Customs purposes they should use the consignor property to identify the sender.

To (Consignee) Address

This is the recipient's address and it will be the location the shipment is delivered to. It's checked and corrected by the system but it can be overridden if necessary by setting the override property to true. If the address is not found an error will be returned to the user unless overridden.

From (Return) Address

The from address is the return address the sender wishes to have their shipment returned to in case there is a problem with the delivery. This is not the same thing as the consignor but it can be the same address. Currently only addresses in the United States (US) can be used as a return address.

System Timezone

All datetimes in the responses are in UTC unless specified otherwise. Tracking events are displayed in the location's local time.

Routine Cleaning

In order to reduce unnecessary clutter the system will routinely purge unused data. Below are a list of objects that should be considered ephemeral and not relied upon.

  • Test shipments and their labels that are older than 30 days.
  • Shipments with no labels that are older than 30 days.
  • Cartons with no shipments that are older than 30 days.

Billing

Credit and Balance

Most users will need to prepay before being able to create production labels. The amount a user adds to their balance will appear as a credit which is a positive number. As the user creates labels (debit) their balance will decrease. Cancelling a label will credit money back to the user's balance. Users won't be allowed to create production labels if the cost of the label brings their balance below 0 unless they have an established credit limit.

Some users are granted a credit limit which allows their balance to go below 0. This negative balance is the amount owed to BoxC. Users with a credit limit won't be allowed to create labels if the cost of the label brings their balance below the credit limit. They must add funds to their balance.

Invoices

Invoices are generated any time labels, overpacks, returns, reshipments, and orders are processed through our system. Labels that are never processed and orders not fulfilled will not be billed. Your previous invoices are available by using the Invoices resource or at your account's Invoices page.

Payments

You can make a payment using the information at your account's Payments page. Contact Support if there are any issues or questions.

Libraries

Depending on your preferred programming language, or that of your application, you can use an existing library created by the BoxC team or the community. You can modify the code to fulfill the requirements of your application. At the very least it will provide a better understanding on how to interact with the API's resources.