Click&Collect API

Headers

Content-Type: application/json
Authorization: Basic base64({projectId}:{applicationKey})
x-localz-chanid: server

Body

{
    "orders": [
        {
            "branchId": "branchId005",    (store number where order belongs to. If stores concept not supported (often true for Field Services), to be set to 1000)(required)
            "orderId": "13149258",        (unique identifier of the order) (required)
            "secondaryReference": "555",  (client's reference of the order) (optional)
            "grouping": "morning_run1",  (client's grouping of the orders) (optional)
            "sequence": 1,  (sequence number of orders. Might be related to grouping, might be not) (optional)
            "stopId": "stopId",  (an Id that is used for orders that delivered "together" - same driver, same time, same address. Driver can start tracking of all orders that belong to the same stopId in one call.) (optional)
            "orderStatus": "PENDING",     (either PENDING - initial order status, PENDING_PACKED - order prepared for delivery (field services usecase), READY - order ready for collection (Collection usecase), CANCELLED - order cancelled, COMPLETE - order completed, FAILEDCOMPLETE - failed delivery, DISPATCH - order ready for tracking, ARRIVING - dispatched order is arriving to destination)(required)
            "scheduleStatus": "CONFIRMED",     (used for customer scheduling. either CUSTOMER_PENDING, CONFIRMED, CONFIRMED_PENDING, CANCELLED_PENDING, SCHEDULED, RESCHEDULED, or UNSCHEDULED)
            "orderDate": "2015-08-06T18:09:00.000Z", (timestamp (in ISO8601 format) when order is scheduled for. Or 'any' time in the date (adjusted to the timezone) that Job is scheduled for. This timestamps will be used for housekeeping of jobs, for example 'show today's orders'.)(required)
            "availFrom": "2015-08-06T18:09:00.000Z", (Start time of the service window in ISO8601 format) (optional)
            "availTo": "2015-08-06T18:09:00.000Z", (End time of the service window in ISO8601 format) (optional)
            "plannedWorkDuration": 300, (Duration of time in seconds that it is expected to last) (optional)
            "fulfiller": "currier123", (Id of the company that will be acting on this order or job. To remove fulfiller, pass null in this field) (optional)
            "completedTime": "2015-08-06T20:09:00.000Z", (only applicable when orderStatus is COMPLETE) (optional)
            "cancelledTime": "2015-08-06T20:09:00.000Z", (only applicable when orderStatus is CANCELLED) (optional)
            "totalAmount": 100.17, (order amount) (optional)
            "currency": "AUD", (order currency) (optional)
            "totalOrderItems": 16, (total number of items that order must have)(optional)
            "collectionPoint": "Drive Through", (for collection usecase, collection point of the store (if multiple)) (optional)
            "isPriority": true, (whether collection of delivery of order require expedite processing) (optional)
            "expectedDeliveryTime": "2015-08-06T20:30:00.000Z", (for collection usecase, the expected delivery time of order to end customer (if for local 2 local delivery applicable)) (optional)
            "customer": {
                "id": "123",    (unique identifier of customer. The id must be used authenticate when authenticating in customer application.) (mandatory)
                "mobile": "+61401010101", (customer landline or mobile number, preferably in E.164 format) (optional)
                "email": "email@email.com", (customer email) (optional)
                "title": "title", (customer title) (option)
                "firstName": "FirstName", (customer first name) (optional)
                "lastName": "LastName", (customer last name) (optional)
                "membershipId": membershipId", (loalty card number. Can be encrypted for privacy purposes. If provided, customer can use this details to checkin order) (optional)
                "commsOptOut": true (if true, don't send sms to customer) (optional)
            },
            "customerInstructions": ["Instruction 1", "Instruction 2"], (instructions that customer provided) (optional)
            "nominees": [{
                "mobile": "+61401010101", (landline or mobile number of alternative contact who can collect the order) (optional)
                "email": "email@email.com", (email address of alternative contact who can collect the order) (optional)
                "title": "title", (title of alternative contact who can collect the order) (optional)
                "firstName": "FirstName", (first name of alternative contact who can collect the order) (optional)
                "lastName": "LastName" (last name of alternative contact who can collect the order) (optional)
            }],
            "user": {  (often request for delivery and field services usecase. employee, technician, engineer, etc. person who will be serving this order. If order already allocated to user and need to be unallocated, set user to null) (optional)
                 "id": "123", (mandatory, string, Login id that user will be logged into application)
                 "mobile": "+61401010101", (mobile (or landline) of user. Maybe used for customer callback and sms back) (optional)
                 "firstName": "FirstName", (first name of user) (optional)
                 "lastName": "LastName", (last name of user) (optional)
            },
            "address": { (for delivery and field services usecase address where service will be performed or order delivered) (optional)
                 "country": "Australia", (the country) (requried)
                 "locality": "Melbourne", (the locality, or suburb) (optional)
                 "region": "VIC", (region or state) (optional)
                 "postcode": "3000", (postal code) (optional)
                 "streetAddress": "412 Collins St", (street address) (required)
                 "subStreetAddress": "level 9", (sub street address - floor, room, unit, etc.) (optional)
                 "latitude": -57.12345, (latitude of the address) - include to skip geocoding (optional)
                 "longitude": 105.12345, (longitude of the address) - include to skip geocoding (optional)
            },
            "payments": [{ (array of payments for the order, including refunds)
                  "amount": 10.50, (amount) (required)
                  "dateTime": "2015-08-06T20:30:00.000Z", (date when payment was made or refunded) (optional),
                  "method": "MASTERCARD", (method of payment, specific to each project) (optional),
                  "details": "xxxxxxxxxxxx7788", (any additional details of payment) (optional),
                  isRedemption: false, (set to true if this payment or refund was a redemption of loyalty point or similar) (optional),
                  isRefund: false, (set to true if this if this is refund) (optional)
            }],
            "attributes": { (any key value pairs - key must be string, value must be string or primitive (number, boolean)) (optional)
                "key": "value"
            },
            "returnCustomer": true, (true if this is NOT first order for this customer) (optional)
            "changeLog": [{  (If order changed outside Localz platform, change log can be send to include timestamps of when changes occurred) (optional)
                 "status": "PENDING", (status of the order, either PENDING, PENDING_PICKED, PENDING_PACKED, READY) (required)
                 "date": "2018-08-13T01:08:46.8470000Z", (timestamp when change occurred) (mandatory)
                 "changedBy": "import" (who changed the order, default "import") (optional)
            }],
            "tags": ["source:tagId1", "tagId2"], (array of strings, tags that can help with querying orders) (optional)
            "orderItems": [ (contains items that order consists off) (optional)
                {
                    "orderItemId": "qwe12", (id of the item, must be unique within order) (requried)
                    "status": "READY", (either PENDING, READY, PENDING_PICKED, PENDING_PACKED, CANCELLED, COMPLETE. Note: if order items present, order status is calculated based on order item statuses) (required)
                    "amount": 100.17, (amount of order item) (optional)
                    "stockCode": "stockCode", (item stock code) (optional)
                    "stockName: "stock name", (item stock name) (optional)
                    "quantity": 2, (quantity of items) (optional)
                    "price": 50.25, (price of item) (optional)
                    "subItems": [{ (details of items instances, for example serial numbers of each item) (optional)
                                     id: "SerialNumber1",
                                     attributes: {
                                        attribute1: "value1",
                                        attribute2: "value2"
                                     }
                                  },{
                                     id: "SerialNumber2",
                                     attributes: {
                                        attribute1: "value6",
                                        attribute2: "value9"
                                     }
                                 }],
                    "attributes": { { (any key value pairs - key must be string, value must be string or primitive (number, boolean)) (optional)
                        "key": "value"
                    }
                }
            ],
           "subProjectKey": "brand1", (brand of the order, appicalble only for projects that support multiple brands) (optional)
           "orderType": "orderType", (order type) (optional)
           "domain": "collection", (domain of order, eiher "COL" or "DLV") (optional)
           "checkinId": "checkinId", (order checkin id) (optional)
           "cancelledReasonCode": "cancelledReasonCode", (reason code for cancelled order) (optional)
           "cancelledAdditionalInfo": "cancelledAdditionalInfo", (additional info for cancelled order) (optional)
           "commsChannels": ["email", "sms", "voiceCall", "push"], (channels to use to send comms to customer of this order. If order has commChl null or empty array, it will be ignored ) (optional)
           "langCode": "en", (language codes as per ISO-639-1 to instruct to send comms using this language. To remove value, langCode should be set to null),
           "proofOfDelivery": [  (proof of delivery associated with fail completion of the order. In future completion of order may support proof of delivery as well.
              {
                name: "Card_Image",
                value: "http://server/path/image.jpg",
                contentType: "image"
              },
              {
                name: "Parcel_Barcode",
                value: "12345678",
                contentType: "text"
              },
              {
                name: "dirty",
                value: "true",
                itemId: "itemId1",
                subItemId: "subItemId5",
                contentType: "text"
              }
            ]
        }
    ],
    "deleted": ["order_1", "order_2"] (alternative way to cancel order. List of orderIds that to be cancelled) (optional)
}
API also accepts single order import format, in which case the payload is:
{
    "orders":
        {
            "branchId": "branchId005",    (store number where order belongs to. If stores concept not supported (often true for Field Services), to be set to 1000)(required)
            "orderId": "13149258",        (unique identifier of the order) (required)
            ...... etc.
        }
}

Body

{
  "failed": [
    {
      "id": "failedOrderId",
      "reason": "error message"
    }
  ]
}

Headers

Content-Type: in case of single order import in case of single order import only

Body

{
  "message": "orderId: 701328556 error: error message",
  "code": "CC-400"
}