Best Practices

ChannelApe's order management is a sophisticated way of managing your sales channel or b2b orders that also ties into your inventory management. This article outlines what configuration and fields are important to get the most out of the ChannelApe ecosystem.

Channel Setup

Install your favorite channel and pull in orders or create a webhook channel to place created orders. Orders can not exist outside of a channel currently.

If you want to enable automated inventory adjustments(see below) when orders occur ensure you have a location set on the channel. Location is an optional field on the channel but it should look something like below.

/v1/orders POST

{
    "additionalFields": [],
    "businessId": "0ba2563e-92fa-41e8-98e1-97361c3e608a",
    "createdAt": "2021-07-01T09:31:24.698Z",
    "enabled": true,
    "integrationId": "a586f946-1209-4822-a145-d9cadc94495e",
    "locationId": "123",
    "name": "My Cool Webhook Channel",
    "settings": {
        "allowCreate": true,
        "allowDelete": false,
        "allowRead": true,
        "allowUpdate": true,
        "disableVariants": false,
        "outputFile": {
            "header": true,
            "columns": []
        },
        "priceType": "retail",
        "updateFields": []
    },
    "updatedAt": "2021-07-01T09:35:59.107Z"
}

Order statuses and their meaning

• OPEN - The order has been placed but there is still a chance to make changes. Usually used in playbook with our Customer Service Window functionality that allows CX agents to be able to make a change to an order before the order is sent to the warehouse.
• HOLD - Their is something wrong with the order and it has been placed in this status for a CX team member to review. Possibly issues would be around shipping address being invalid.
• IN_PROGRESS - The order has been fully or partially sent to the warehouse to be fulfilled. It's ideal that no changes come into the order at this point unless the warehouse supports it, but this is rare.
• CLOSED - The order has been fulfilled completely or the order has been closed on the channel. Once in this status, there is nothing else to do with the order, and these are filtered out of most of ChannelApe processing.
• CANCELED - The order has been canceled by either the customer or the warehouse.

Creating an Order

To get an order into the order management system you need to create it in ChannelApe. There are a few fields to note when creating an order.

Order level fields

• channelOrderId - The external identifier for the order. This needs to be unique per business.
• purchaseOrderNumber - The purchase order number for the order. This is optional and can be shared across orders but generally should be unique as well.
• channel - The channel you created above
• status - The current status of the order. Ideally should be placed in OPEN and let the ChannelApe order management system take it the rest of the way.
• purchasedAt - The time the order was placed.
• alphabeticCurrencyCode - The three letter ISO 4217 currency code. (USD, CAD)

Customer

Information about the customer. The main thing ChannelApe uses here are the shipping and billing address. But these fields can also further identify the customer for the order.

• email
• phone
• name

Customer Address (Shipping and Billing Address)

• address1
• address2
• city
• province
• provinceCode
• country
• countryCode
• postalCode

Line Items

Each order placed needs at least one item.

• id - a unique identifier, that is required. This is how ChannelApe will try to identify line items.
• sku - A string that represents a product. If you want automated inventory adjustments, then this should match inventory item sku in the ChannelApe Inventory Management system. It will keep track of quantities of all skus on the order that the system knows about and ignore the rest.
• quantity - The quantity being ordered. Note: that once created you can only increase this number. ChannelApe API will prevent you from reducing this number.
• price - the cost * quantity ordered.

Finally, the order should look something like this when creating it.

{
    "alphabeticCurrencyCode": "USD",
    "channelId": "42b714f4-9372-46db-8892-605a53fd4ae4",
    "channelOrderId": "demotest-id-1",
    "customer": {
        "billingAddress": {
            "address1": "224 Wyoming Ave",
            "address2": "Suite 100",
            "city": "Scranton",
            "province": "Pennsylvania",
            "country": "United States",
            "postalCode": "18503"
        },
        "email": "jdoe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "shippingAddress": {
            "address1": "224 Wyoming Ave",
            "address2": "Suite 100",
            "city": "Scranton",
            "province": "Pennsylvania",
            "country": "United States",
            "postalCode": "18503"
        }
    },
    "lineItems": [
        {
            "id": "123",
            "quantity": 2,
            "sku": "ABC-123",
            "price": "99.99"
        }
    ],
    "purchaseOrderNumber": "po-1",
    "purchasedAt": "2023-11-14T16:02:05.000Z",
    "status": "IN_PROGRESS"
}

Fulfilling an Order

Fulfillments on an order are the way to identify when an item on the order is shipped.

If you are responsible for creating fulfilllments on a ChannelApe order, there a few important things to keep in mind.

Fulfillment Statuses and their meanings

• PENDING - The fulfillment that is usually created when it is sent to the warehouse.
• OPEN - The fulfillment was received back from the warehouse and has enough information to pass back to the channel. If you are not using external systems to communicate the fulfillment, you most likely do not need this status.
• SUCCESS - The fulfillment has all of the tracking information and no more information is needed.

Fulfillment level fields

• id - All fulfillments need an ID. This field is technically not required currently but going forward it will be generated for you if you do not pass one in.
• lineItems - See above
• trackingNumber - The tracking number for the shipment
• shippingMethod - The method for which the box is shipping.
• shippingCompany - the company that will be handling the shipping.

You can use /v1/orders PATCH

{
    "fulfillments": [
        {
            "id": "456",
            "lineItems": [
                {
                    "id": "123",
                    "price": "99.99",
                    "quantity": 1,
                    "sku": "ABC-123"
                }
            ],
            "shippedAt": "2023-11-16T15:54:03.239Z",
            "status": "SUCCESS",
            "trackingUrls": []
        }
    ]
}

Automated inventory adjustments

If you follow the above the following inventory adjustments should automatically happen. Note that these only happen if the location is set on the channel and the line item sku is found in channelape.

Action	Adjustment(s)
Order is created in channelape	+1 committed for each item * quantity
Order is updated with a new line item	+1 committed for the new item * quantity
Line Item quantity is increased on order item	+1 committed for each new quantity
New fulfillment moving to SUCCESS status	-1 committed and -1 available for each item in the fulfillment
Refund line item created with a restock_type of cancel	-1 Committed for each item.