"Coordinates of the recipient (customer) location [delivery point]" within a certain delivery order

Questions
, , ,
1

Hi to all,

If it won’t be considered some sort of spam, I am writing here on behalf of a team who would like to integrate their solutions with “Square PoS” systems.

Our solution (called Internodz) is a “delivery pooling” tool for on-demand (food, grocery etc.) delivery operations as explained here.

You can think of it as the independent (exported) version of the two sub-features (sub-services) called “Uber Eats Pool” and “Postmates Party” inside “Uber Eats” and “Postmates”.

Through those sub-services inside “Uber Eats” and “Postmates”, “person B” and “person C” can add their orders into an already scheduled delivery for “person A” in the same vicinity, with some promotions (discounts) on the “delivery fees”, “minimum order values” and/or “total order amounts” etc.

In order to make the same scenario real for the businesses with their own delivery fleets (couriers), our solution is also informing people on a route of a scheduled delivery if the coordinates of the “store/shop/business/restaurant/grocery” and the “delivery point” are known.

While we are searching for our answers in Square’s developer documents and this forum both, we also thought that we could leave (share) our questions here and get some support from Square experts, in order to avoid missing required points (details).

Thanks a lot in advance for any help.

Here are our questions.

Through Square APIs, - for a certain “delivery order” ;
1-) Can we get the “location data (coordinates)” of the business/store/shop/restaurant?
2-) Can we get the “location data (coordinates)” of the delivery point (customer, recipient)?
3-) If both above are possible, what are the names of the “objects/parameters/properties/attributes/fields” that we should use?

2

Hi @mustafa welcome to the forums!

  1. Yes, using the Locations API it will return an address as well as coordinates.
  2. No, you will only be able to see the address supplied by the customer/application. We also only support PICKUP and SHIPMENT fulfillments through our API currently.
  3. In the Locations API the field is literally called coordinates. The latter doesn’t have a coordinates field. You can get the address, though, if the application does a SHIPMENT fulfillment, you would need to retrieve the order using BatchRetrieveOrders. It would live in order->fulfillments->shipment_details->recipient->address.
3

I was looking for the coordinates of a location in the documentation, they are listed on this page

1 Like
4

Thanks so much for the info, @rickypanzer .

5

Thanks a lot for such a detailed reply, @sjosey.

It may sound a bit exaggerated but I would really like to appreciate the effort and patience displayed by you and the Square team to help people on this forum.

Could I also ask how reliable can it be for us to use “SHIPMENT” fulfillment within the Square API?
Do “Square” clients use “SHIPMENT” fulfillment for their on-demand (quick, instant) deliveries?
Or is it better for us to wait for the launch of “DELIVERY” fulfillment feature in Square’s API? As far as I see, there is already someone else waiting for (and requesting) this feature?

Thanks once again.

1 Like
6

Hi @mustafa, I think it’s totally fine for you to use SHIPMENT however you see fit and however it works for you, sine we do not offer DELIVERY and I do not have an ETA on when it will be offered unfortunately.

8

My apologies to everyone for re-posting my entry again since I was late to update the previous one. It is not for taking more attention, apologies once again.

Hi @sjosey,

Despite a long time since my first input in this thread which should have been already enough to design the required integration schema, I was just able to prepare only the one below and just decided to share it publicly with its all immatureness to ask you and the Square expert team and also the community on the forum first if it includes anything opposite to the Square’s mentality (working mindset), that might be something not possible for it to do.

And in order to make it clear if such a scenario (in the schema) is convenient (appropriate) for Square (in case I might miss some tricky/key/main points while exploring the “Square” through my own personal efforts), here are my first initial questions to be a start point:

1-) [The first stage in the schema]

Rather than converting the text-based “order->fulfillments->shipment_details->recipient->address” data into coordinates, we humbly consider working with the coordinates data taken directly from the end-user himself.

But in this method, we will probably need the information whether or not the customer uses his own address (which already recorded/exists in his “customer card” in the Square PoS) as the recipient address within the related order. Might there be any way to check it? Perhaps by using/adding some additional custom fields/attributes etc. if the standard (original) version of Square PoS doesn’t provide?

2-) [The third stage in the schema]

It is not a mandatory thing but, through “webhooks”, can Square notify us for new orders based on some additional conditions/filters? For example, just for those whose, “fulfilment” types are “SHIPMENT”.

3-) [Again the third stage in the schema]

The vice versa, - not a mandatory thing again but -, through “Orders API”, could we query Square orders based on some additional conditions/filters? For example, just for those whose, “fulfilment” types are “SHIPMENT”.

4-) // Not a question - Just aloud thinking //

If neither “2” nor “3” is possible, then we can already filter (sort) orders at our side. “2” and “3” are just in case, some Square clients might not want to share their all orders with us, however, as far as I guess, the data within the Orders API includes almost nothing in terms of “the privacy of the personal data” unless we don’t query anything with “customer ID”.

5-) [Still the third stage in the schema]

If a Square client (business) request not to use their all customers data through this integration scenario and want to restrict it for just the users benefiting (using) our solution (Internodz), can we use the “customer group” property/attribute for that purpose while querying/inserting or updating the customers through the Customers API?

6-) [The last thing about the third stage in the schema]

Might it be possible to sub-categorize/classify “SHIPMENT” orders more in detail using/adding by some additional custom fields/attributes/properties etc. as listed below?

  • One group as “to be delivered by third-party (outsourced) logistics partners (couriers)”
  • The other group as “to be delivered by the business’ own deliverers (employees)”

Would be so grateful for any kind of reply, comment, review and help from anyone.

Thanks so much.

The schema is also available at https://docs.google.com/drawings/d/1RjGK5B76oOmt6w8tAwAUBet1QnWKoeniUZ93QpFULqo/edit?usp=sharing

Internodz_with_Square_PoS
Internodz_with_Square_PoS564×2500 203 KB

9

Hi @mustafa I will try to answer your questions below:

  1. I’m not sure I’m following this. What are you meaning by coordinates in the address context (it should just be a street address)? Also, what do you mean that the address already exists in his customer card? We do not ask for address when a customer checks out through POS, that would be something you need to ask for if you need to use it.
  2. No, unfortunately not. It will notify you for all orders, so you would need to do the filtering within your application.
  3. Sure, the SearchOrders endpoint allows you to do queries, including by fulfillment type.
  4. See 3, let me know if that doesn’t make sense though.
  5. There’s only one single CUSTOMERS_READ permission though OAuth; if I’m understanding you correctly, the business would either need to let you read all or none of their customers information.
  6. You can use the metadata field to add just about anything you want to an Order. See more information here: https://developer.squareup.com/docs/build-basics/metadata
10

Thanks for another prompt reply @sjosey,

  1. I am just trying to mean the customers giving orders remotely by phone calls or online channels to get their items delivered. Doesn’t “Square PoS” keep any “address” data for those kinds of customers?
11

If you’re collecting it, sure. Somewhere you have to be collecting the address whether it’s online or via POS. It won’t be done automatically, for example.

12

So the question is, can those collected data (address information) be used as the recipient address for the next orders of the same customer ?

13

If you’ve saved it somewhere you can look it up, like a Customer profile, then yes of course you can use the address however you want including in Order addresses.

14

Sorry, @sjosey, for making such a simple subject complex and thanks once again for your patience.

    1. In our case, we might need to detect if “the recipient address in the order” is the customer’s already saved address.
      If we can not, we will have to convert “the recipient address in the order” to coordinates (latitude, longitude) by “geocoding” but “geocoding” sometimes doesn’t work right, returns errors/wrong results/nothing (because of its nature).
      But if we can detect it, then we can use “that saved address” with its coordinates (which is provided earlier by the customer himself through our solution, “coordinates” are saved in our solution, matched with the “Customer IDs” in Square) . I just tried to demonstrate it at the stage “①” in the schema.
    1. From your reply;
      You can use the metadata field to add just about anything you want to an Order. See more information here: https://developer.squareup.com/docs/build-basics/metadata
      I just saw “OrderSource”. I will ask my question with the most primitive version in order to make it clear. Who does decide what to be filled (typed) in “OrderSource” ? “The Square client (Business)” or “the external application creating orders in Square”? Particularly for the scenario below;

Let’s say there is a restaurant taking orders inside the place (1. to serve to the tables, 2. by PICKUP) physically and through phone calls and three individual online platforms (Online_Source_1, Online_Source_2, Online_Source_3). Can the OrderSource be categorized as follow;

1- Table
2- PICKUP
3- Phone
4- Online_Source_1
5- Online_Source_2
6- Online_Source_3

15

So for 1, if you have the address saved in the customer profile, you should be able to just look it up and compare. As for geocoding, I doubt it will always be the same due to its nature, so it might be better to use actual addresses rather than geocoding if you need to confirm the address.

For the order source, it’s up to the application. Most first party products do not fill the source field, so it’ll be null for POS/dashboard payments. Your application can supply the field when calling CreateOrder, though. You can make the source whatever you want, it’s just a string value.

1 Like
16

@sjosey just I don’t know what to say, you don’t only reply to our questions but also think on behalf of us. Thanks so much.

We will probably use the comparison method. Thanks for the suggestion. It sounds like the most healthy way.

Nevertheless, apart from the Square API, is there any way to enhance (customize) the Square PoS system itself in order to be able to put “those saved addresses” into the “recipient address” automatically by just clicking a “radio button” for returning customers on the phones? For example, by just selecting one such as “home”, “work”, “school” etc? - The purpose is just to avoid typing errors while filling the “recipient address” manually.

17

In the scenario, what do you actually mean by “recipient address”? If you’re using the basic Square POS application, you can simply attach an existing customer profile to a payment. There’s no way to customize the Square POS directly, but we do have APIs/SDKs that allow you to create your own POS (such as POS API, Reader SDK, and Terminal API).

18

In the scenario, what do you actually mean by “recipient address”?

Sorry, I might have named it “wrong” by just importing (bringing) from a general delivery process which might not be experienced often in Square’s clients’ businesses.

I’m just naming it so, because of “gift sending” -like scenarios, the customer buys his items from the seller in order to make them (items) be delivered to someone else (recipient). - It’s not related to our scenario/case (or solution), mine is just a habit of using that specific term.

If you’re using the basic Square POS application, you can simply attach an existing customer profile to a payment.

This will solve our problem, thanks.

My question

5-) If a Square client (business) request not to use their all customers data through this integration scenario and want to restrict it for just the users benefiting (using) our solution (Internodz), can we use the “customer group” property/attribute for that purpose while querying/inserting or updating the customers through the Customers API?

Your reply

  1. There’s only one single CUSTOMERS_READ permission though OAuth; if I’m understanding you correctly, the business would either need to let you read all or none of their customers information.

1-) May the “Customer Groups API” (announced today) change anything?

2-) My question initially was for querying customers but perhaps we might not need to search/query/read customers, since I just saw that the docs also mention “CUSTOMERS_CREATE” and “CUSTOMERS_WRITE” permissions. If the Square itself is able to merge duplicate records inside, can we use those permissions? First we create a customer, Square returns a “customer ID”, we collect those data at our side, then (when needed) we can update any of those customers (created by only “us”) based on those returned IDs. But, I guess, Square assigns another ID to merged records? And also, what does it return as a response to a creation attempt, if the record already exists?

19
  1. Can you clarify what you’re actually trying to do here? I thought you were talking about OAuth permissions, which doesn’t have anything to do with Customer Groups.
  2. If you’re going to create customers, you would need CUSTOMERS_WRITE permission, yes, If two customer records are merged (which can only be done via the Square Dashboard, and not via API), then a new customer is created with a new customer id, with the merged data. We do not check for duplicate data, so if you try to create a customer with the same name and email as existing customer, then it will succeed.
20

  1. We can skip that question @sjosey, I learnt so recently after typing here that the Customer Groups API is totally unrelated to our case. I should have checked it before asking here.

  2. Thanks once again for replying with all the details.

Actually, the thing I have been worrying is whether or not providing such full permissions to third-party platforms may cause (raise) any issue in the regions where the Square currently operates, in terms of the privacy of personal data?

It allows developers to query without any filter and get all the customers data from the business.

I just personally don’t know if there are any legal restrictions in those regions for the content of the data to be shared between the stakeholders but, as far as I know, there are quite strict rules in some other parts of the world, just as it is in the EU region.

Even if there are no such restrictions in the regions (countries) that Square currently operates, I just worry what the business owners’ general approaches would be to that subject/point.

(Hope my style of writing doesn’t sound like an aloud reaction? :thinking: :slight_smile: )

21

The merchant must approve your application, and they will be presented with a screen of what permissions your application is asking for, and the customer information would’ve willingly been given to the merchant already. There are no legal issues to be aware of as far as I’m aware. Customers in the EU can reach out to Square if they want their data completely erased from Square, and we are legally obligated to cooperate of course.

Of course, if the merchant doesn’t want you to have access to their customer’s data, then they would simply deny (not approve) your application and thus you won’t be able to access it.