Promotions implementation guide for integrated brands

Depending on the promotions you want to run through NuORDER by Lightspeed, it will influence the updates you may need to make to your integration.

Note: If you are already mapping pricing fields from the order export to your ERP, no changes may be needed to support promotions.

Review your promotions

Review your promotions and group them into the categories that NuORDER supports:

  • Order level discount ($ or % off).
  • Line item level discount ($ or % off by style number or product grouping).
  • Discount available to all retailers or to specific retailers.

back to top

Review your integration

Review the order export and note which pricing fields are currently being mapped:

  • Line item price per (is this the selling price (including discounts) or the base price (excluding discounts).
  • Discount rate.
  • Order total (does this include shipping costs or other surcharges?).
  • Shipping fees.
  • Surcharges.

Note: Inclusion of pricing on the order export does not mean that pricing is mapped. Be sure to confirm what fields are mapped and how the ERP ingests pricing that is different from the expected line item price.

Review how your ERP calculates the line item price or order level total:

Common behavior is the ERP uses the assigned pricing based on the SKU/UPC + account code & ship to code. If there are promotional programs configured, it will also apply additional discounts if applicable.

Some systems do not allow line item level or order level overrides without a specific value that is associated with a promotional program.

Order level discounts:

  • If the discount should be applied at the order level, does the order total map? If yes, can the order export override the pricing set by the ERP?
  • Do you have promotions set up in your ERP? How does the promotion/discount get applied to the order?
  • Do not create order level promotions if your ERP can only consume discounts at the line item level. The discounted order total is not applied at the line item level.
    • For example, if you set an order level promotion for $10 off a $100 order and 4 units are ordered at $25 each. The pricing on an order will appear like this: $25 x 4 = $90, not $22.50 x 4 = $90.

Line item level discounts:

  • Does the line item price map? If yes, can the order export override the pricing set by the ERP?
  • If no pricing fields are currently mapped from the order export, can this be updated so that the line item price is mapped and can override the pricing set by the ERP?
  • Do you need to receive the base price and the discount rate separately? Or the selling price with discounts already calculated?
  • Do you have promotions set up in your ERP? How does the promotion/discount get applied to the order?

Note: After reviewing the above, if you need to update your integration, reach out to your Account Manager.

back to top

Technical specifications

Integrated brands who opt to receive promotional data in their order export from NuORDER can update their order export to include the following fields. Please see sample JSON further down in this document for examples.

Order level discounts

Parameter Definition
discounted_total Final order total after discounts.
original_total Total of order without discount.
total_after_line_item_discount Total of order after line item discounts.
total_applied Total discount applicable for order.
name Name of applied discount.
description Description of applied discount.
discount Amount of applied discount.
surcharge Surcharge on an order.
company_manual_discount Manually entered company discount for the specified order
total_order_level_discount Total order level promotion applied.
shipping_final_amount Total shipping paid on order.


Item level discounts

Parameter Definition
total_applied Total discounts applied on item.
effective_subtotal Effective subtotal.
original_total Total of item before discount.
discounted_total Total of item after discount.
item_price_after_discount Item price after discounts.
adjusted_wholesale_string Wholesale price of item.
total_adjustment Total adjustment.


Size level discounts (part of item level discounts)

Parameter Definition
total_discount Total discount in particular size.
name Name of applied discount on size.
description Description of applied discount on size.
discount Amount of applied discount on size.


back to top

API output

The following JSON represents the JSON data for the following two endpoints:

  • /api/order/:id
  • /api/order/number/:number

Endpoint: /api/order/:id

{
    "_id": "63b53bb9eac247e6f619efe1",
    "split": false,
    "buyer_submitted": false,
    "easy_order_viewed": false,
    "easy_order_ready": false,
    "collaborative_draft": false,
    "edited": false,
    "payment_status": "Not Paid",
    "is_drop_ship": false,
    "__shipment_status": [],
    "__uninitiated_order": false,
    "__includes_cancelled": false,
    "__cancelled_units": 0,
    "__cancelled_total": 0,
    "__is_rtp": false,
    "order_tags": [],
    "creator_name": "saurav pampatwar",
    "schema_id": "62ce9dcf2f431212fdae1faa",
    "line_items": [
        {
            "product": {
                "_id": "62cea2792f43129a0eae293d",
                "style_number": "SAMSUNG_F",
                "color": "white",
                "color_code": "",
                "season": "spring"
            },
            "ship_start": "2023-01-04T00:00:00.000Z",
            "ship_end": "2023-02-03T00:00:00.000Z",
            "total_applied": "-42",
            "effective_subtotal": "142.2",
            "original_total": "200",
            "discounted_total": "142.2",
            "item_price_after_discount": "$79.00",
            "adjusted_wholesale_string": "$100.00",
            "total_adjustment": "-15.8",
            "company_manual_discount_on_item": "-20",
            "item_manual_discount_on_item": "-18",
            "applied": [
                {
                    "_id": "63b53bbceac2476b5919eff9",
                    "name": "Item level 2",
                    "description": "$2 off",
                    "discount": "-4",
                    "price_code": "03239150-7cdc-4a36-b39b-0b2d87fae047",
                    "currency_code": "USD"
                }
            ],
            "sizes": [
                {
                    "size": "M",
                    "quantity": 2,
                    "price": 71.1,
                    "original_price": 100,
                    "units_per_pack": 1,
                    "discounts": {
                        "total_discount": -42,
                        "_id": "63b53bbceac2474aff19effb",
                        "applied": [
                            {
                                "_id": "63b53bbceac247132a19effc",
                                "name": "Item level 2",
                                "description": "$2 off",
                                "discount": "-4",
                                "price_code": "03239150-7cdc-4a36-b39b-0b2d87fae047",
                                "currency_code": "USD"
                            }
                        ]
                    },
                    "surcharges": {
                        "total_surcharge": "0",
                        "applied": []
                    }
                }
            ],
            "surcharges": {
                "total_surcharge": "0",
                "applied": []
            },
            "discount": 10,
            "warehouse": "Warehouse1",
            "prebook": false
        }
    ],
    "status": "pending",
    "currency_code": "USD",
    "order_group_id": "63b53b63eac2473ecb19eef3",
    "total": 162.42,
    "selected_shipping_locations": [],
    "__split_overrides": [
        {
            "_id": "63b53bbaeac2475a2919eff1",
            "key": "_default_2023/01/04"
        }
    ],
    "__configure_to_order_items": [],
    "shipments": [],
    "order_number": "30638016",
    "modified_on": "2023-01-04T08:41:31.539Z",
    "additional_percentage": 10,
    "additional_percentage_label": "Tax",
    "discount": 10,
    "notes": "",
    "retailer": {
        "_id": "62cea504edaef12dfafdf341",
        "retailer_name": "InstaPlay",
        "retailer_code": "",
        "buyer_name": "Sam",
        "buyer_email": "saran@gmail.com"
    },
    "submitted_by": "web",
    "tech_pdf": "63b53bb9eac2477e7a19efea",
    "total_quantity": 2,
    "billing_address": {
        "line_1": "New York",
        "country": "United States",
        "zip": "90067"
    },
    "shipping_address": {
        "line_1": "121 Los Angeles",
        "country": "United States",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90067"
    },
    "customer_po_number": "",
    "locked": false,
    "existing_pdf_linesheet": "63b53bb9eac247fc6419efe5",
    "admin_pdf": "63b53bb9eac247ba4b19efe6",
    "manager_pdf": "63b53bb9eac247489519efe7",
    "rep_pdf": "63b53bb9eac247509b19efe8",
    "buyer_pdf": "63b53bb9eac2473e3819efe9",
    "created_on": "2023-01-04T08:41:30.738Z",
    "shipping_information": {
        "service_type": "FedEx Ground®",
        "service_code": "fedex_ground",
        "carrier_code": "fedex",
        "carrier_friendly_name": "FedEx",
        "price": "6.00",
        "final_amount": "6.00"
    },
    "rep_name": "Sam",
    "rep_code": "",
    "rep_email": "sau@gmail.com",
    "start_ship": "2023-01-04T00:00:00.000Z",
    "end_ship": "2023-02-03T00:00:00.000Z",
    "order_discounts": {
        "discounted_total": "162.42",
        "original_total": "200",
        "total_after_line_item_discount": "158",
        "total_applied": "-57.8",
        "total_order_level_discount": "-15.8",
        "applied": [
            {
                "_id": "63b53bbceac2475c1419effd",
                "name": "Order level promotion 10 % off",
                "description": "",
                "discount": "-15.8",
                "price_code": "c7229d8a-2c35-4734-9a8d-bbaa55b039fe",
                "currency_code": "USD"
            }
        ],
        "surcharge": "14.22",
        "company_manual_discount": "-20",
        "shipping_final_amount": "6",
        "surcharges": {
            "total_surcharge": "0",
            "applied": [
                {
                    "name": "",
                    "_id": "63b53bbceac24779c819effe",
                    "price": "0",
                    "currency_code": "USD",
                    "price_code": "total_surcharges"
                }
            ]
        }
    }
}

 

Endpoint: /api/order/number/:number

{
    "_id": "63b53bb9eac247e6f619efe1",
    "split": false,
    "buyer_submitted": false,
    "easy_order_viewed": false,
    "easy_order_ready": false,
    "collaborative_draft": false,
    "edited": false,
    "payment_status": "Not Paid",
    "is_drop_ship": false,
    "__shipment_status": [],
    "__uninitiated_order": false,
    "__includes_cancelled": false,
    "__cancelled_units": 0,
    "__cancelled_total": 0,
    "__is_rtp": false,
    "order_tags": [],
    "creator_name": "saurav pampatwar",
    "schema_id": "62ce9dcf2f431212fdae1faa",
    "line_items": [
        {
            "product": {
                "_id": "62cea2792f43129a0eae293d",
                "style_number": "SAMSUNG_F",
                "color": "white",
                "color_code": "",
                "season": "spring"
            },
            "ship_start": "2023-01-04T00:00:00.000Z",
            "ship_end": "2023-02-03T00:00:00.000Z",
            "total_applied": "-42",
            "effective_subtotal": "142.2",
            "original_total": "200",
            "discounted_total": "142.2",
            "item_price_after_discount": "$79.00",
            "adjusted_wholesale_string": "$100.00",
            "total_adjustment": "-15.8",
            "company_manual_discount_on_item": "-20",
            "item_manual_discount_on_item": "-18",
            "applied": [
                {
                    "_id": "63b53bbceac2476b5919eff9",
                    "name": "Item level 2",
                    "description": "$2 off",
                    "discount": "-4",
                    "price_code": "03239150-7cdc-4a36-b39b-0b2d87fae047",
                    "currency_code": "USD"
                }
            ],
            "sizes": [
                {
                    "size": "M",
                    "quantity": 2,
                    "price": 71.1,
                    "original_price": 100,
                    "units_per_pack": 1,
                    "discounts": {
                        "total_discount": -42,
                        "_id": "63b53bbceac2474aff19effb",
                        "applied": [
                            {
                                "_id": "63b53bbceac247132a19effc",
                                "name": "Item level 2",
                                "description": "$2 off",
                                "discount": "-4",
                                "price_code": "03239150-7cdc-4a36-b39b-0b2d87fae047",
                                "currency_code": "USD"
                            }
                        ]
                    },
                    "surcharges": {
                        "total_surcharge": "0",
                        "applied": []
                    }
                }
            ],
            "surcharges": {
                "total_surcharge": "0",
                "applied": []
            },
            "discount": 10,
            "warehouse": "Warehouse1",
            "prebook": false
        }
    ],
    "status": "pending",
    "currency_code": "USD",
    "order_group_id": "63b53b63eac2473ecb19eef3",
    "total": 162.42,
    "selected_shipping_locations": [],
    "__split_overrides": [
        {
            "_id": "63b53bbaeac2475a2919eff1",
            "key": "_default_2023/01/04"
        }
    ],
    "__configure_to_order_items": [],
    "shipments": [],
    "order_number": "30638016",
    "modified_on": "2023-01-04T08:41:31.539Z",
    "additional_percentage": 10,
    "additional_percentage_label": "Tax",
    "discount": 10,
    "notes": "",
    "retailer": {
        "_id": "62cea504edaef12dfafdf341",
        "retailer_name": "InstaPlay",
        "retailer_code": "",
        "buyer_name": "Sam",
        "buyer_email": "saran@gmail.com"
    },
    "submitted_by": "web",
    "tech_pdf": "63b53bb9eac2477e7a19efea",
    "total_quantity": 2,
    "billing_address": {
        "line_1": "New York",
        "country": "United States",
        "zip": "90067"
    },
    "shipping_address": {
        "line_1": "121 Los Angeles",
        "country": "United States",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90067"
    },
    "customer_po_number": "",
    "locked": false,
    "existing_pdf_linesheet": "63b53bb9eac247fc6419efe5",
    "admin_pdf": "63b53bb9eac247ba4b19efe6",
    "manager_pdf": "63b53bb9eac247489519efe7",
    "rep_pdf": "63b53bb9eac247509b19efe8",
    "buyer_pdf": "63b53bb9eac2473e3819efe9",
    "created_on": "2023-01-04T08:41:30.738Z",
    "shipping_information": {
        "service_type": "FedEx Ground®",
        "service_code": "fedex_ground",
        "carrier_code": "fedex",
        "carrier_friendly_name": "FedEx",
        "price": "6.00",
        "final_amount": "6.00"
    },
    "rep_name": "Sam",
    "rep_code": "",
    "rep_email": "sau@gmail.com",
    "start_ship": "2023-01-04T00:00:00.000Z",
    "end_ship": "2023-02-03T00:00:00.000Z",
    "order_discounts": {
        "discounted_total": "162.42",
        "original_total": "200",
        "total_after_line_item_discount": "158",
        "total_applied": "-57.8",
        "total_order_level_discount": "-15.8",
        "applied": [
            {
                "_id": "63b53bbceac2475c1419effd",
                "name": "Order level promotion 10 % off",
                "description": "",
                "discount": "-15.8",
                "price_code": "c7229d8a-2c35-4734-9a8d-bbaa55b039fe",
                "currency_code": "USD"
            }
        ],
        "surcharge": "14.22",
        "company_manual_discount": "-20",
        "shipping_final_amount": "6",
        "surcharges": {
            "total_surcharge": "0",
            "applied": [
                {
                    "name": "",
                    "_id": "63b53bbceac24779c819effe",
                    "price": "0",
                    "currency_code": "USD",
                    "price_code": "total_surcharges"
                }
            ]
        }
    }
}

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request