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.

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. Clients can force which warehouse is used for order fulfillment.

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 summary on how to get started with BoxC's API including setting up your first integration.

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. Test shipments can be created by using the test property.

Authentication

All requests to the API require an Access Token associated with a user and client. Authenticated users must authorize your client to act on their behalf when interacting with the various resources. The scope of the access token depends on the client's permission settings. You can find more details about how to use the tokens and make authenticated requests on the OAuth 2.0 page.

Rate Limit

This version of the API utilizes rate limiting for requests. It uses the leaky bucket algorithm to calculate the amount of requests that are granted every second up to a maximum number of requests. All rate limits are currently calculated against a user's ID across all applications. By default users are limited to a maximum of 30 requests with 2 new requests added to the bucket every second. There is no limit on the aggregate number of requests that can be made. The API returns a JSON response with error code 1015 while the limit is temporarily exceeded.

The response includes two header lines to assist developers in staying within their limits:

X-Rate-Limit: m
X-Rate-Requests: p

Where m is the maximum requests or bucket size and p is the number of current requests. The number of remaining requests can be calculated as m - p.

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"
}

Paginate

When "searching" entities like Shipments and Orders there might be thousands of results. In order to reduce response time results are limited or "paged". Each response from the server will include the next_page property at the root level to assist in navigating to the next page of results. If no page exists after the current page then this property will be null. After making the initial query to an endpoint subsequent queries need only specify the page_token parameter in the request like below:

https://api.boxc.com/v1/shipments?page_token=ZGF0ZV9zdGFydD0yMDIzLTA0LTI5JmRhdGVfZW5kPTIwMjMtMDctMjgmbGltaXQ9NTAmb3JkZXI9ZGVzYyZsYWJlbGVkPSZwYWNrZWQ9JnBhZ2U9MSZwcm9jZXNzZWQ9Jmxhc3RfaWQ9ODIyMTE3OA==

This tells the API which page to load. You no longer need to pass every query parameter after the initial search since it's tokenized. Your application can temporarily cache the page tokens for navigating backwards or forwards as needed.

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.

Consignor (Seller) 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 (Shipping) Address

The to address is the shipping address; it should be the final location of the shipment. In most cases it's the same as the consignee address. An error is returned when the address can't be validated and/or verified. Each country and carrier has its own rules and regulations.

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 if needed. Shipments will use an address provided by BoxC if one isn't given. Return and shipping address countries must match.

Consignee (Buyer) Address

The consignee is the buyer of the goods. In most cases this is the same as the shipping address so the shipment will use that as the consignee by default if one isn't provided. Consignee and shipping address countries must be the same.

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.
  • Orders not fulfilled and older than 1 year are deleted.
  • Inbound shipments 3 years and older are deleted.
  • Fulfilled orders are moved to the Archived status after 90 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 and Statements

Invoices are generated every Monday for the previous week's transactions. A transaction takes place when you create a shipment or make a payment for example. If there were no transactions during the previous week then an invoice will not be created. 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.