API requests

[steve byerly]

Hey Shippo team. I was hoping to pass along some feature requests for future versions of the API. I've spent quite a bit of time in the API and python client and have run into a few roadblocks. Let me know if you have any questions on any of these points.

• A general 'Test Mode' with distinct, separate test api keys.
• Multiple users per-account with group perms.
• Generate manifests (SCAN forms at least) separately from production labels. 
• I've found no way to make SCAN forms for my test labels only.
• Manually update resources. 
• From what I can tell, there's no way to push updated information back for an existing object_id. Instead I have to create new objects.
• Change a shipment to be scan-based without specifying the `return_of` field.
• Our business sends the client something that needs to be returned 100% of the time. Sometimes, the client may opt to expedite shipping and use their own return. In these instances we would use the scan-based labels so that we're not out the shipping cost if the label is not used. We don't always want to use scan-based as we'd be out the extra $0.25 over 99% of the time.
• Related, don't swap the from/to addresses if I specify them. If I'm passing in the addresses explicitly, then I would rather them not get changed from under me.
• Handle time-zones
• I had a hard time generating SCAN forms for awhile before realizing that they were using UTC datetimes as day cutoffs. If I specify a submission date, it should respect my timezone, if present, and let me include labels from that day.
• E.g. I'm in PST. I generate 10 labels from 8AM to 4:00 PM and 2 labels from 4:00 PM to 4:30 PM. If I try to generate a SCAN form for all 12 labels (explicitly passing the transaction IDs) and the current datetime for PST (say 4:45 PM), I will get an error because the 10 labels generated before 4:00 PM are a different day in UTC time.
• Our workaround is to make multiple SCAN forms based on the UTC date - so we often have one with 40-50 labels, and one with 2-3.
• Provide an endpoint for me to get default parcels for a carrier (all possible templates/dimensions).
• I wanted to pre-load my database, but found no authoritative location for this information. I found one spot on the site, but the information didn't seem to be complete/up to date.
• Handle address validation properly
• It seems that some of the APIs don't actually do the work, they just pass them along to a 3-rd party like Endicia. This is bad if I'm expecting something like address validation to work as I would expect.
• E.g. I sent an address along to validate and purposefully changed the state (let's say a NY address and changed state to WA). Instead of getting an 'INVALID' address back, I got a 'VALID' address back and the state was changed automatically. This doesn't really help as my system needs to know if the address was valid or not so we can either contact the client, or update our own data.
• Our workaround is to compare all fields to our own data since we have to assume all VALID addresses could have changed data

[Simon Kreuz]

Hey Steve,

thanks so much for the detailed feedback - that's really helpful! Our product team is checking it out right now and we'll get back to you with more feedback soon. 

Cheers,

Simon

[Simon Kreuz]

Hi Steve,

again, thank you for the detailed feedback! We've reviewed it internally:

1. Test mode: absolutely - we're aware that a separate test environment would make the integration and testing much easier. We have this project on our roadmap for this year. Due to the rather big scope of the change we don't have a final timeline yet, but are hoping to roll it out this year.
   
2. Multiple users per account: same - we understand the need for this and have it on our roadmap.
   
3. Test Manifests: along with the separate test mode (1) we will add this functionality.
   
4. Updating resources: our current API design is not built around updating most resources (there are exceptions such as e.g. Carrier Accounts). We are considering to change this in future API versions, but don't have a concrete roadmap for it yet.
   
5. Scan-based return labels: this improvement is on our roadmap as well, planned for Q2 or Q3 the latest.
   
6. Manifest time-zones: we have created a ticket for this bug and will work on it in one of the upcoming sprints - I'm sorry that you had to build a workaround for this, we should handle the timezone properly on our end.
   
7. Parcel Template list: that's a great point - sorry for the confusion! We've moved the Parcel Templates to its own Enum section in our docs here https://goshippo.com/docs/#parceltemplates. I hope that's clearer!
   
8. Address validation: our address validation endpoint automatically tries to identify an address. If a default address has been found without any ambiguity we automatically correct and clean the address. The endpoint returns "invalid" only if multiple or no addresses have been found. I understand that it would be helpful to also expose a flag that indicates if we have changed the address - we've added that to our improvements list. That being said, would you still prefer the endpoint to not automatically correct the address? Our assumption is that this is helpful because you don't even need to contact your customer - are we missing a use case here?
   

Let me know if that makes sense or if I can clarify our feedback. We're constantly improving the API and your feedback is really helpful in prioritizing our work.

Thanks,

Simon

[steve byerly]

Hi Simon,

Thanks for the update and the work you all are doing - it is much appreciated. Here are a few extra details in case you may find them useful:

4. I failed to mention that the only time I've really wanted to update a resource is to change a shipment to become scan-based after the fact. 

Our workflow was setup to: choose packaging for outbound/return, select rates, purchase labels. The outbound and return packaging is chosen together since the outbound weight is dependent on the (supplied) return packaging. We would never include a return shipment in certain circumstances, but it was then decided to optionally allow for scan-based returns. I originally thought about updating the created return shipment based on user input, but had to move to delaying the return 'shipment' object creation until the outbound label was made.

I have a solution that works well that I have no need to change, so not really a priority at this point.

8. My use-case is probably different than most of your clients. We integrated shippo well after our normal e-commerce setup, so we already have a system that tracks/validates addresses. We were hoping to catch address changes during label-creation so we could also update them other places in the DB. This all could be circumvented by doing the address validation at the time of user-input as opposed to generating our labels.

Thanks again for taking the time to review. Please let me know if you ever need alpha/beta testers.

-Steve