Overview
Use custom endpoints to pull shipping rates from your own database or other system.
Custom endpoints are treated as individual rates and can be added to any product group / shipping zone.
You can manage your custom endpoints in the app on the Settings tab.
Custom Endpoints are available on the Unlimited Plan.
How it works
When calculating shipping rates, Advanced Shipping Rules sends a request to your custom endpoint. The request contains an order's origin address, destination address, and a list of the items being ordered.
Your custom endpoint returns shipping rates for the order, provided in JSON format.
Advanced Shipping Rules works as usual, using the rates returned from your custom endpoint -- rules are applied, blended rates are calculated when applicable, and the final shipping rates are displayed to a customer at checkout.
Adding a custom endpoint
You can add a custom endpoint on the Settings tab or on the Add Rate page (when you add a new rate to any product group / zone).
Custom Endpoint Settings
Label - required
- The label allows you to identify the custom endpoint within the app; it is not shown to customers.
Description - optional
- You can use the description to add any helpful info that describes the rates being returned from this endpoint. It's not shown to customers.
Endpoint URL - required
- This is the full URL of your custom endpoint that will return shipping rates. All URLs must use SSL and begin with https://
Username / Password - optional
- Enter a username and password combo to be used for HTTP Basic Auth when sending requests to your custom endpoint.
When you save a custom endpoint, we perform a test call to your endpoint to make sure rates are returned.
For this test call, both the origin and destination will be your shop's address.
Make sure your endpoint returns rates when shipping to/from your shop's address.
Requests made to your custom endpoints
At checkout, ASR makes an HTTP Request to your custom endpoint. ASR POSTs json to your endpoint containing an order's origin address, destination address, and a list of the items being ordered in the following format:
{
"origin":
{
"country":"US",
"zip":"94117",
"state":"CA",
"city":"San Francisco",
"address":"123 Main St",
"address2":"Apt 2A",
"phone":"+18558392222",
"name":"David Dingo",
"company_name":"David's Dingos"
},
"destination":
{
"country":"US",
"zip":"11211",
"state":"NY",
"city":"Brooklyn",
"address":"321 Main St",
"address2":false,
"phone":false,
"name":"Jack Mahon",
"company_name":false
},
"items":
[
{
"name":"Ferndale Pillow Cover",
"sku":"ferndale-cvr",
"quantity":1,
"grams":453,
"price":1999,
"vendor":"Covers",
"requires_shipping":true,
"taxable":true,
"fulfillment_service":"manual",
"properties":{},
"product_id":4648141315,
"variant_id":54748807192
}
]
}
Custom Endpoint Responses
Your custom endpoint must return a json array of Rate Objects in the following format:
[
{
"service_name": "Ground",
"description": "2 - 5 days",
"service_code": "ground",
"currency": "USD",
"rate": 1299
},
{
"service_name": "Overnight",
"description": "1 day",
"service_code": "overnight",
"currency": "USD",
"rate": 5400
}
]
Your endpoint must send a response within 5 seconds or rates will not be returned.
Rate Object
service_name - string - required
Your custom endpoint must return service_name (which becomes the rate title).
*You can override this value in the app by editing the Rate Title field on the Edit Rate page.
description - string - optional
If your custom endpoint returns rate descriptions, they are used as rate subtitles.
*You can override this value in the app by editing the Rate Subtitle field on the Edit Rate page.
service_code - string - optional
If your custom endpoint does not return a service_code, the service code "custom-endpoint" will be used.
*You can override this value in the app by enabling custom service codes and editing the Service Code field on the Edit Rate page.
currency - ISO 3-letter currency code - optional
Currency defaults to USD unless otherwise specified. Rates are converted into your shop's currency before they're displayed at checkout to provide a consistent shopping experience.
rate - int - required
The shipping rate, or price, for the service. All rates must be returned as an integer, in cents. For example, a $5.25 rate must be returned as 525.