Getting Started

If you don’t have access to Canal yet, please request it here. If you have received access, please visit the Canal App and confirm that your login credentials work. If you have any issues, contact us at [email protected].

In this guide, you will find information on the following:

  1. Onboarding Steps

  2. Authentication

  3. Environments

  4. Webhooks

  5. Developer Documentation


Onboarding Steps

Step 1: Complete the Canal onboarding flow

When you first log in to your Canal account, you will need to fill in a few details before you can start using the product. Please complete this flow as thoroughly as you can. One step will be to add in Webhooks; however, this is optional and can be completed at a later time in the Developer tab in Settings. Learn more about Webhooks.

Step 2: Choose a Supplier through Discover or invite a Supplier to Canal

Note: Steps 2-3 are not necessary to complete the implementation of Canal's API. We recommend that you first use the Development environment to test your implementation. This environment already contains test products for your usage. If you use the Development environment, head directly to Step 4. Learn about the Development environment

In the Canal app, Suppliers are listed in the Discover tab. You can browse Suppliers by category and brand values to find the right partners for your Store.

If you don’t find the Suppliers you need in the Canal app, or are looking to work with your existing Suppliers, you can invite a new Supplier to Canal.

Step 3: Establish partnership terms with proposals

You can send a proposal to a Supplier from the Discover tab, or to your invited supplier once they’ve downloaded Canal.

Proposals are lightweight contracts between a Storefront and a Supplier. In a proposal, you can select the products you’d like to sell, propose commission terms, and determine shipping settings. You can go back and forth with your supplier during the proposal stage until you’ve agreed to terms that suit your needs.

Step 4: Add approved products to your Storefront

You can easily add Supplier products to your Store via the Canal API. Canal will send all the necessary data for you to create your own Product Detail Pages for these products. Please see the API Reference for details on how to do so.

To ensure your Storefront always has all the new products you have added on the Canal app, you should create a webhook for the product/create topic so that the products are automatically sent to your Storefront when you are approved to sell the products and have added them to your Store on the Canal app.

You will also want to create a webhook for the product/update topic so that any product updates made by the Suppliers can be sent to your Storefront and be updated automatically.


Step 5: Integrate order creation into your Store

When a customer purchases a Canal-powered Supplier product, you must create a new order containing that product. To do so, please use the Orders endpoints in the Canal API.

Note: To know how much you should charge the customer for shipping, please use the Shipping Rates endpoints in the Canal API.

To receive updates regarding orders placed through your Storefront, please create a webhook for the order/update topic, which will send you the updates automatically.

Additonally, to receive fulfillment details for the order once the Supplier creates a new fulfillment job, please create webhooks for the fulfillment/create and fulfillment/update topics.

Step 6: Integrate refunds into your Store

When a customer requests for a refund for a Canal-powered Supplier product, you will need to generate a refund through Canal. Please use the Refunds endpoints in the Canal API to create a new Refund request.


Step 7: Start selling!

You are now ready to sell Canal-powered Supplier products. When customers pay you, Canal will charge you via ACH to pay the Suppliers for their products, leaving you with your earned commission. You can learn more about payments in the Help Center.


Authentication

Required Credentials

The Canal API uses a combination of an Application ID and API Access Token to authenticate requests. For all REST Admin API requests, you will need to include the following as headers in the requests:

  • x-canal-app-id: Application ID

  • x-canal-app-token: API Access Token

Obtaining App ID and API Token

Your Application ID and API Access Token are both automatically generated for you when your account is created. You can find these values in the Developer tab in Settings under “API Credentials” after you log into your account in the Canal App.


Environments

Overview

The Canal API provides access to two environments - development and live. These environments are identical in functionality, with the key intention being to give developers the ability to test their stores in development before going live. The primary differences between the environments are:

  1. Any orders placed in the development environment are fake and do not have any dollars transacted or fulfillments. A fake Stripe card number is used for the “payment.”

  2. The URL endpoint begins with https://api-develop.shopcanal.com instead of https://api.shopcanal.com.

  3. The API Tokens are different for each environment. You can find the development API token in Settings on Canal's Developer App and the live API token in Settings at shopcanal.com/login.

We highly recommend that you first complete implementation using the Development environment and then use the Live environment once you are ready to sell.

Development

To use the Development environment:

  1. Use the API Token specified in Settings under “API Credentials” on Canal's Developer App [Note: this is a different link than the Live App link].

  2. Use the https://api-develop.shopcanal.com URL endpoint for all API calls.

After logging into your Canal Development account, you will find pre-approved products that you can use for the purpose of testing your API implementation.

Live

To use the Live environment:

  1. Use the API Token specified in Settings under “API Credentials” on the Canal App [Note: this is a different link than the Developer App link].

  2. Use the https://api.shopcanal.com URL endpoint for all API calls.


Webhooks

Overview

Webhooks allow your application to subscribe to events that occur within Canal, giving you updates whenever there is a change made by Canal or a Canal-powered Supplier. The current set of webhooks that are available for use are listed under "Webhook Topics" below.

Webhook Topics

You can currently subscribe to any of the following webhooks:

  • order/create: When your Storefront creates an order for a Canal-powered Supplier, Canal will send an order confirmation to your application.

  • order/update: When an update is made to a Canal-powered Supplier order that was created via your Storefront, Canal will send the new information to your application.

  • product/create: When your Storefront is approved to sell a specific product, you must first go to the Canal app and click the "Add to store" button next to the product in the Inventory tab. When this button is clicked, the webhook will send the product's data to your application so that it can be added to your Storefront.

  • product/update: When a Canal-powered product on your Storefront is updated by the Supplier, such as the product's price or description, Canal will use this webhook to send the new data to your application.

  • fulfillment/create: When a Canal Supplier creates a new fulfillment job for an order placed via your Storefront, Canal will send the data about the fulfillment to your application.

  • fulfillment/update: When a Supplier updates and existing fulfillment job for an order placed via your Storefront, Canal will send the update to your application.

Webhook Registration

There are two methods to register a webhook:

Method 1: Canal App

To register a new webhook:

  1. Log into your account on the Canal app.

  2. Visit the Developer tab in Settings. You can find Settings in the dropdown under your brand's name in the top right.

  3. Scroll down to the section called "Add Webhooks."

  4. Click on "Add webhook" and enter in the information requested.

  5. Click "Run test" in the modal and ensure you receive a confirmation message that the webhook has been successfully verified. If you get an error, please make changes accordingly.

Method 2: Terminal

You can perform the same actions as above using commands in your terminal. You can POST a request to the /webhooks/ endpoint with all the necessary information. An example of what this may look like is:

curl https://api.shopcanal.com/platform/webhooks/ 
--request POST \ --header 'Content-Type: application/json' \
--header 'x-canal-app-id: xxxx-xxxx-xxxx-xxxx' \
--header 'x-canal-app-token: your_canal_api_access_token' \
--data '{ "topic": "product/create", "address": "https://api.storefront.com/webhook-sink" }'

You can find more information in the developer docs.

Webhook Verification

Before you respond to a webhook, you need to verify that the webhook was sent from Canal. Canal will send the following headers in the request: x-canal-app-id, x-canal-topic, and x-canal-event-hash. You can verify the webhook's authenticity by hashing the request body with your Application ID and comparing it to the x-canal-event-hash value that is sent in the headers of the request.

The hash is generated using sha256:

hmac.new(app_id, msg=utf_8_encoded_data, digestmod=hashlib.sha256)

Developer Documentation

For complete documentation of all endpoints available via the Canal API, please visit our developer documentation.

If you have any questions throughout the process, contact us at [email protected].

Did this answer your question?