Overview

Corso's Commerce API is used by merchants to manage data about their orders, including basic data about the orders themselves as well as follow-up information such as any fulfillments that occur associated with an order.

The Commerce API would generally be used in conjunction with the Shop API. The Shop API is for quoting Green Shipping Protection for a cart and helping the integration add it to an order, and then the Commerce API will be used to keep Corso aware of the details needed about the order once it is completed.

A typical use of the API might look like the following:

Send new orders to Corso

When a new order is placed, that order is sent to the /orders endpoint as a POST. The body will contain a full order object including any customer information and order line items.

We recommend sending all orders regardless of their protection status, since customers may look up orders that they didn't protect. being able to inform the customer at that time that their orders isn't protected is only possible if all orders are in Corso systems - otherwise our process will be to inform them that we do not see the order. Typically the customers will be referred back to the merchant when this is the case.

Send fulfillments to Corso

Each time an order is fulfilled, it should be sent to Corso as a POST to the /orders/{orderId}/fulfillments endpoint. These fulfillment updates allow Corso to see tracking numbers and help with any carrier issues.

Orders may be fulfilled multiple times, with items split across different shipments.

Other operations

There are other cases where changes might be need to be conveyed to Corso. For example:

• If a customer cancels an order, you can issue a DELETE /orders/{orderId} with details.
• If an order needs to be updated, a POST to the /orders/{orderId} endpoint can perform that update. Note that Corso does not use PATCH or PUT for updates, relying instead on POST. This is a less-common pattern, but it is a RESTful approach that reduces ambiguity around the usage of different verbs.
• If the order line items change, Corso should be updated of those as well. Line items are individually immutable, and updating specific line items should be done by deleting and replacing them. Canceling a line item is done with a DELETE /orders/{orderId}/line-items/{lineItemId}. Adding a new line item is done via POST /orders/{orderId}/line-items.

Data formats

Various data formats are used consistently throughout the API. A few guidelines to keep in mind:

Currency

Currency codes are always expected in ISO 4217 format. These include commonly used abbreviations such as USD for the United States Dollar, EUR for the Euro, JPY for the Japanese Yen, etc.

Currency values are stored with 2 digits of precision. A dollar amount of $12.3412111 will be stored by Corso as $12.34, for example.

All money values must be transmitted in the base currency of your store, as configured with Corso. This value can be examined with a call to GET /stores/{storeId} if there is any doubt.

Dates and Times

The Commerce API does not accept dates without times anywhere, instead requiring a full datetime string. Because the Corso Commerce API leverages the OpenAPI 3.0 standard, these different fields are specified as date-time, which means RFC 3339 format. Most commonly-used ISO 8601 strings are RFC 3339 compliant as well. More details on formats, especially the differences between ISO 8601 and RFC 3339 can be found here: https://ijmacd.github.io/rfc3339-iso8601/

Virtually all modern language standard libraries generate a compliant datetime string with little or no adaptation, but care should be taken to ensure that the offset is included.

To summarize the standard, a valid RFC 3339 string contains all of the following:

• Date, in a format similar to 2023-02-28
• Time, in a format similar to 16:24:40
• A separator between the date and time. "T" is valid and commonly used, as is a space character.
• The offset, expressed as either hours:minutes from UTC or "Z" to indicate UTC.

The following are all valid RFC 3339 strings:

• 2022-02-28T16:24:00.33Z
• 2022-02-28T16:24:00Z
• 2022-02-28T16:24:00-0:00
• 2022-02-28 16:24:00Z

We may parse non-compliant strings and assume any missing information. Not including an offset will not be considered an error for example, but we will assume UTC.

Sub-second values will be parsed and stored, but not guaranteed at the precision sent by an API client.

Since most datetime values sent to the Commerce API will be returned in the response body, it should be confirmed during development that the expected value is being stored and returned.

Phone numbers

Phone number values should be sent as E.164 strings. More information about this standard is available at https://en.wikipedia.org/wiki/E.164. Corso does not validate the phone numbers beyond checking the following:

• The string starts with a +
• There are no more than 15 numeric characters following the plus.
• The first character after the plus is NOT a 0, since no country codes start with 0.

Phone numbers for subscribers in the United States and Canada can generally have a +1 added to the area code and phone number combination to make it a valid E.164 phone number, after all non-numeric characters are removed. For example, (800) 867-5309, 1-800-867-5309, and 800 867 5309 should all be transmitted as +18008675309.

You can check strings for compliance with the standard (but not for phone number validity) using a RegEx similar to the following: ^\+[1-9]\d{1,14}$

Data model

Conceptually, the Commerce API deals with several related resources, including:

• Customer
• Order
• Order Line Item
• Address
• Fulfillment
• Store

These are related as follows:

OAS files

The Open API Specification files for this API can be downloaded in both JSON and YAML format.

These files are auto-generated from our API code, and can be considered to be fully accurate at the time of download.