Using the app proxy

Learn how to fetch information about your rates using the secure app proxy provided by Postcode Shipping.

Whilst the Postcode Shipping app does not provide any widgets that your customers can interact with on your store, we do provide an app proxy that you (or a developer that you hire) can use to build your own.

Parts of this guide are a little more technical than most articles on this support site as it is designed to help developers use our app proxy in a custom integration.

What is an app proxy?

If you’re not familiar with the concept of a ‘proxy’ it essentially refers to a URL that is part of your Shopify store domain - e.g. https://your-store.myshopify.com/apps/postcode-shipping - that forwards (or ‘proxies’) any calls made to it onto a specific URL in the Postcode Shipping app.

One use of an app proxy would be to add a simple widget on your site that a customer can use to find out if you provide shipping rates for their postcode. The flow of data in this example would look a bit like this:

Customer enters their postcode into your custom widget.
The widget sends this postcode to the proxy URL on your store https://your-store.myshopify.com/apps/postcode-shipping.
Shopify receives this request, adds some authentication data to it and then forwards it onto the correct URL on the Postcode Shipping app.
We process the request and send back a response to your customer via your widget.

Using an app proxy has two main benefits:

You can use the proxy to make a call to Postcode Shipping from javascript that is included as part of your shop theme. Browsers can block calls made to a URL that is not part of the same domain (due to security concerns) whereas making a call to your own domain avoids this scenario.

Calls via an app proxy can be made securely without the need for API keys or other forms of authentication. Simply send a request to your app proxy and Shopify will send us the authentication information we require to make sure that the request is genuine.

How to customise the app proxy

By default, the app proxy for Postcode Shipping is:

( https://yourshop.myshopify.com/apps/postcode-shipping )

You are free to modify the URL and can do so within Shopify admin by heading to your list of installed apps and clicking to Postcode Shipping. You’ll see a screen like this:



You can change the /apps/ part of the URL to:

/a/
/community/
/tools/

You are also free to change the /postcode-shipping part of the URL to whatever you like, for example you could change it to /rates if you prefer.

In the documentation below we’ll stick to the default proxy URL:

https://your-shop.myshopify.com/apps/postcode-shipping

What can you do with the Postcode Shipping app proxy?

We provide two proxy URLs that you can use to retrieve different information about your rates.

Check
https://your-shop.myshopify.com/apps/postcode-shipping/check

This endpoint accepts customer address data and returns true or false based on whether you have any rates that cover that address.

You can call this proxy URL using either a GET or a POST request and it accepts the following data:

country - valid two-letter country code (required)
postal_code - spaces and casing are ignored (required unless postcodes are optional in the country in question)
address1 - (optional)
address2 - (optional)
address3 - (optional)
city - (optional)
province - (optional)

If sending a GET request, the address data should be included in the URL as a query string. If sending a POST request the address data should be sent as a JSON payload.

The app will send back a JSON response from this endpoint in the format:

{

  "rates_available": true

}

Quote

https://your-shop.myshopify.com/apps/postcode-shipping/quote

This endpoint accepts customer address data and a summary of the current cart contents and returns a set of matching rates.

You can call this proxy URL using either a GET or a POST request and it accepts the following data:

country - valid two-letter country code (required)
postal_code - spaces and casing are ignored (required unless postcodes are optional in the country in question)
city - (optional)
province - (optional)
grams - an integer representing the total weight of all items in the cart. (optional)
price - an integer representing the total cost of all items in the cart. This should be the value expressed in the lowest denomination for the specified currency e.g. cents, pence etc (optional)
quantity - an integer representing the total number of items of all kinds in the cart (optional)
currency - a valid three-letter currency code (optional)

If sending a GET request, the address data should be included in the URL as a query string. If sending a POST request the address data should be sent as a JSON payload.

The app will send back a JSON response from this endpoint in the format:

{

  "rates": [

    {
      "service_name": ,
      "service_code": "my_first_rate",
      "description": "A description of my first rate",
      "total_price": 1050,
      "currency": "AUD
    },
    {
      "service_name": "My second matching rate",
      "service_code": "my_second_rate",
      "description": "A description of my second rate",
      "total_price": 2100,
      "currency": "AUD
    }
 ]
}

Updated on: 23/11/2022