Cascade

    Importing orders

    Bring your order history across from another platform so Cascade knows who bought what, can ask the right customers for reviews, and can credit loyalty points for past purchases.

    Before you start

    Every order attaches to a customer and to the products it contains, so import those first:

    1. Importing products.

    2. Your customers, from Customers. Cascade matches each order to a customer by email address.

      The Import orders dialog with the review request and loyalty switches turned off

    Skip this and every order is skipped for want of something to attach to.

    Import your orders

    1. Export your orders from your current platform as a CSV file and arrange the columns to match the list under For developers below. Each item in an order is one row, with the order's own details repeated on every row.

    2. Open Orders, choose Import from the actions menu, and pick your file.

    3. Decide about the two switches on the import dialog. Both start off, so importing history never emails your customers or hands out points by accident:

      • Send review requests checks each imported order against your survey flows and emails the customers whose orders match.
      • Earn loyalty rewards gives imported orders points and stamps.

    4. Start the import. It runs in the background, so you can leave the page.

    5. Check Settings → Imports when it finishes. Open the job to see any rows that were skipped, with the row number and the reason.

      A finished orders import listing the orders it created

    Good to know

    • Importing the same file again is safe. Cascade recognizes each order by the order ID from your old platform and updates it in place, replacing its items with the ones in the file, rather than adding a copy.
    • One bad item skips the whole order. Cascade won't import an order with only some of its items. Fix the row and import again.
    • A bad row never stops the import. The rest of the file lands.

    If something isn't working

    • "No customer with the email ..." That customer hasn't been imported yet. Import your customers, then run the orders file again.
    • "No product with the slug ..." The product isn't in Cascade, or its handle is spelled differently. Check it under Products.
    • Nobody got a review request. The Send review requests switch was off, or the orders didn't match a flow. See Collecting reviews.

    Next steps

    For developers

    One row per line item. Rows that share a remoteId are one order, wherever they sit in the file. Files in the older format (a full row starts an order, the rows below carry only their line item) still import: a row with a blank remoteId belongs to the order above it.

    ColumnRequiredDescription
    customerYesEmail of the customer who placed the order. Must already exist.
    remoteIdYesThe order's ID in the system you are migrating from. Ties the rows of one order together.
    numberYesThe order number shown to the customer.
    totalCentsYesOrder total in the smallest currency unit (5999 for $59.99).
    productNoSlug of the product on this row. Must already exist. Blank for an order with no line items.
    productVariantNoSlug of the variant bought, if the product has variants.
    quantityNoUnits bought. Required when product is filled.
    unitPriceCentsNoPrice of one unit, in the smallest currency unit. Required when product is filled.
    siteNoSlug of the site the order was placed on. Defaults to your first site.
    subtotalCentsNoDiscounted subtotal excluding shipping and tax. Loyalty earning uses it where given.
    shippingCentsNoShipping charged.
    taxCentsNoTax charged.
    currencyCodeNoISO 4217 code. Defaults to USD.
    shippedAtNoWhen the order shipped, e.g. 2024-01-15T10:30:00Z. Blank if it hasn't.
    deliveredAtNoWhen the order was delivered.
    cancelledAtNoWhen the order was canceled.
    metadataNoA JSON object of your own string key/value pairs.
    customer,remoteId,number,totalCents,product,quantity,unitPriceCents
ada@example.com,1001,ORD-1001,5998,classic-tee,1,1999
ada@example.com,1001,ORD-1001,5998,plant-pot,1,3999

    Where two rows of one order disagree on an order-level value, the first non-empty value in the file wins and the ignored row is reported. A blank cell means "not specified" and never overwrites what another row said. The same import is available as POST /import-jobs.