Introduction
Welcome to the ScriptDrop Pricing API.
Pricing API v1 returns delivery price quotes for decision support. The first implementation supports USPS Ground Advantage quotes.
A quote request is used only to calculate an available caller-facing price. It does not create a delivery order, reserve a rate, create a label, persist a quote resource, or lock pricing for a later shipment or label purchase.
Pricing API v1 responses are intentionally minimal. They do not include zone,
quote expiration, rate-lock terms, label-purchase terms, carrier package codes,
signature requirements, tax line items, fee breakdowns, surcharge breakdowns,
or delivery-order identifiers.
Quote requests are safe to retry because they do not create orders, labels, or persistent quote records.
Environments
| Environment | Quote endpoint |
|---|---|
| Production | https://request.scriptdrop.co/pricing/v1/quotes |
| Sandbox | https://request.sandbox.scriptdrop.io/pricing/v1/quotes |
Sandbox and production use separate credentials. Contact ScriptDrop for the appropriate API key and secret; do not reuse sandbox credentials in production.
Authentication
Authentication uses HTTP Basic authentication.
The API key is sent as the Basic auth username. The API secret is sent as the Basic auth password.
To authorize, use this code:
api_key = "pk_myapikey1234"
api_secret = "sk_myapisecret1234"
encoded_authorization = Base.encode64("#{api_key}:#{api_secret}")
authorization_header = "Basic #{encoded_authorization}"
export SCRIPTDROP_API_KEY="pk_myapikey1234"
export SCRIPTDROP_API_SECRET="sk_myapisecret1234"
curl --request POST "https://request.scriptdrop.co/pricing/v1/quotes" \
--user "$SCRIPTDROP_API_KEY:$SCRIPTDROP_API_SECRET" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"pickup": { "address": { "zipcode": "43215" } },
"dropoff": { "address": { "zipcode": "43210" } },
"providers": ["usps"],
"service_level": "ground_advantage",
"package_dimensions": {
"length_in": 8,
"width_in": 5,
"height_in": 3,
"weight_oz": 15
}
}'
ScriptDrop uses API keys to allow access to the API. Please contact our support team for API keys.
ScriptDrop expects API requests to include an Authorization header:
Authorization: Basic encoded_authorization
Authorization
Callers need active, dedicated credentials enabled for Pricing API v1. Credentials issued for another ScriptDrop API surface are not automatically authorized for the Pricing API.
The request body does not accept chain_id, customer_id, or pharmacy_id in
v1. The server selects the rating context for the authenticated credential.
V1 Quotes
Create a Quote
url = "https://request.scriptdrop.co/pricing/v1/quotes"
api_key = "pk_myapikey1234"
api_secret = "sk_myapisecret1234"
encoded_authorization = Base.encode64("#{api_key}:#{api_secret}")
authorization_header = "Basic #{encoded_authorization}"
headers = [
{"Authorization", authorization_header},
{"Content-Type", "application/json"}
]
quote_params = %{
"pickup" => %{
"address" => %{
"zipcode" => "43215"
}
},
"dropoff" => %{
"address" => %{
"zipcode" => "43210"
}
},
"providers" => ["usps"],
"service_level" => "ground_advantage",
"package_dimensions" => %{
"length_in" => 8,
"width_in" => 5,
"height_in" => 3,
"weight_oz" => 15
}
}
HTTPoison.start()
HTTPoison.post(url, Jason.encode!(quote_params), headers)
curl --request POST "https://request.scriptdrop.co/pricing/v1/quotes" \
--user "$SCRIPTDROP_API_KEY:$SCRIPTDROP_API_SECRET" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"pickup": { "address": { "zipcode": "43215" } },
"dropoff": { "address": { "zipcode": "43210" } },
"providers": ["usps"],
"service_level": "ground_advantage",
"package_dimensions": {
"length_in": 8,
"width_in": 5,
"height_in": 3,
"weight_oz": 15
}
}'
The above command returns a
200 OKresponse with JSON structured like this:
{
"quotes": [
{
"provider": "usps",
"service_level": "ground_advantage",
"price_cents": 644,
"currency": "USD"
}
]
}
Endpoint
POST https://request.scriptdrop.co/pricing/v1/quotes
Request Shape
{
"pickup": {
"address": {
"zipcode": "43215"
}
},
"dropoff": {
"address": {
"zipcode": "43210"
}
},
"providers": ["usps"],
"service_level": "ground_advantage",
"package_dimensions": {
"length_in": 8,
"width_in": 5,
"height_in": 3,
"weight_oz": 15
}
}
Required Fields
| Field | Type | Description |
|---|---|---|
pickup.address.zipcode |
string | Pickup ZIP Code. |
dropoff.address.zipcode |
string | Dropoff ZIP Code. |
package_dimensions.length_in |
number | Package length in inches. |
package_dimensions.width_in |
number | Package width in inches. |
package_dimensions.height_in |
number | Package height in inches. |
package_dimensions.weight_oz |
number | Package weight in ounces. |
ZIP Code Format
zipcode must be sent as a string so leading zeros are preserved.
Pricing API v1 accepts 5-digit US ZIP Codes and ZIP+4 values with or without a hyphen. ZIP+4 values are normalized to their first five digits before pricing.
Examples:
"zipcode": "43215"
"zipcode": "02108-1234"
"zipcode": "021081234"
Non-US postal codes, empty strings, and numeric ZIP Code values are not accepted in v1.
Package Dimensions
Pricing API v1 does not infer package weight or dimensions. Consumers may use launch defaults, but the selected values must be sent in the request.
length_in, width_in, height_in, and weight_oz must be positive numbers.
Zero, negative, missing, or non-numeric values are rejected.
Pricing API v1 validates USPS Ground Advantage package eligibility limits as
request validation. Total weight must not exceed 1120 oz (70 lb), and the
longest side plus girth (2 x the sum of the other two dimensions) must
not exceed 130 in. Packages outside either limit are rejected with
422 Unprocessable Content and validation_failed, naming the offending
field (package_dimensions.weight_oz or package_dimensions.girth) in
error.fields.
For packages within those limits, if USPS returns no eligible Ground
Advantage rate for another reason, the API returns 200 OK with
quotes: []. If USPS cannot process or price the package, the API returns
502 Bad Gateway.
ScriptDrop may round package measurements according to carrier-rating rules before calculating the quote. Consumers should send the most accurate available package dimensions and weight.
Carrier package codes, including USPS flat-rate packaging, are not supported in v1.
Optional Filters
| Field | Type | Default | Accepted Values | Description |
|---|---|---|---|---|
providers |
array of strings | ["all"] |
"all", "usps" |
Provider filter. |
service_level |
string | "all" |
"all", "ground_advantage" |
Service-level filter. |
If providers is omitted, the API behaves as if ["all"] was provided.
In v1, ["usps"], ["all"], and an omitted providers value can all return
USPS Ground Advantage quotes when the caller is authorized and a quote is
available.
providers must not be an empty array.
If service_level is omitted, the API behaves as if "all" was provided.
In v1, "ground_advantage", "all", and an omitted service_level value can
all return USPS Ground Advantage quotes when the caller is authorized and a
quote is available.
Response Shape
{
"quotes": [
{
"provider": "usps",
"service_level": "ground_advantage",
"price_cents": 644,
"currency": "USD"
}
]
}
Response Fields
| Field | Type | Description |
|---|---|---|
quotes |
array | List of matching quotes. |
quotes[].provider |
string | Quoted provider. For v1, this is usps. |
quotes[].service_level |
string | Quoted service level. For v1, this is ground_advantage. |
quotes[].price_cents |
integer | USPS Ground Advantage rate selected for the credential's server-configured rating context, in minor currency units. |
quotes[].currency |
string | ISO currency code. For v1, this is USD. |
Price Semantics
price_cents is the USPS Ground Advantage rate selected for the authenticated
credential's server-configured rating context.
For USPS Ground Advantage v1, provider and service_level identify USPS
Ground Advantage as the quoted carrier service. The response does not promise a
USPS retail, commercial, or rate-card classification, and it does not include
caller-configured markup rules in v1.
Taxes are excluded from price_cents. Pricing API v1 does not calculate taxes,
does not return tax line items, and does not return separate fees or surcharges.
Consumers should not present price_cents as tax-inclusive.
Empty Quote Results
When the request is valid and processed but no USPS Ground Advantage quote is
available, the endpoint returns 200 OK with an empty list:
{
"quotes": []
}
An empty quotes list is not an error condition.
The API returns quotes: [] only when the request is syntactically valid, the
caller is authenticated and authorized, and no matching USPS Ground Advantage
quote is available for the requested lane, package, provider, and service-level
filters.
Malformed requests, invalid filters, unsupported values, and authorization
failures return error responses instead of quotes: [].
Request IDs
Each response includes an opaque request identifier in the X-Request-Id
header.
Consumers should include this request identifier when contacting ScriptDrop support about a Pricing API request.
V1 Deferred Features
The following capabilities are intentionally deferred from Pricing API v1:
| Capability | Status |
|---|---|
| Carrier package codes, including USPS flat-rate packaging | Deferred from v1. |
signature_requirement |
Deferred from v1. |
| Tax, fee, or surcharge breakdowns | Deferred from v1. |
| Quote expiration and rate-lock terms | Deferred from v1. |
| Label-purchase terms | Deferred from v1. |
| Quote persistence | Deferred from v1. |
| Rate reservation | Deferred from v1. |
| Label creation | Deferred from v1. |
| Delivery-order creation | Deferred from v1. |
| Delivery-order identifiers | Deferred from v1. |
Pricing-context overrides in the request body: chain_id, customer_id, and pharmacy_id |
Deferred from v1. |
Errors
Error responses use this shape:
{
"error": {
"code": "validation_failed",
"message": "Validation failed",
"fields": {
"package_dimensions.weight_oz": ["can't be blank"]
}
}
}
error.code is stable and machine-readable. Clients should use it to decide
how to handle an error. error.message is human-readable and may change;
clients should not parse it. fields is included for request-validation errors
and maps each invalid field to its validation messages.
Authentication failures return a WWW-Authenticate: Basic realm="Pricing API v1"
header.
The ScriptDrop Pricing API uses the following status and error-code pairs:
| HTTP Status | error.code |
Meaning |
|---|---|---|
| 400 | invalid_request |
The request cannot be parsed as a valid API request. |
| 401 | authentication_required |
Credentials are missing. |
| 401 | authentication_invalid |
Supplied credentials are invalid. |
| 403 | credentials_not_enabled |
The credential is not enabled for Pricing API v1. |
| 403 | credential_owner_unsupported |
The credential owner type is not supported by Pricing API v1. |
| 404 | not_found |
The requested Pricing API v1 route does not exist. |
| 405 | method_not_allowed |
The HTTP method is not supported by the route. |
| 406 | not_acceptable |
The Accept header does not permit an application/json response. |
| 422 | validation_failed |
The request is valid JSON but fails Pricing API validation. |
| 500 | pricing_configuration_error |
ScriptDrop cannot resolve the caller's pricing configuration or rating context. |
| 500 | internal_error |
An unexpected server-side error occurs. |
| 502 | pricing_provider_unavailable |
ScriptDrop cannot obtain a USPS pricing quote. |
| 503 | pricing_temporarily_unavailable |
Pricing API v1 is temporarily paused. |
400 Bad Request
Return 400 Bad Request with invalid_request when the request cannot be
parsed before it reaches Pricing API request validation. Requests that are valid
JSON but fail field or business validation return 422 validation_failed
instead.
401 Unauthorized
Return 401 Unauthorized when the request cannot be authenticated.
Examples:
- missing
Authorizationheader - non-Basic authorization scheme
- malformed Basic credentials
- unknown API key
- secret mismatch
Example:
{
"error": {
"code": "authentication_required",
"message": "Authentication credentials are required"
}
}
Use authentication_invalid when credentials are supplied but invalid.
403 Forbidden
Return 403 Forbidden when the request is authenticated but the credential is
not allowed to perform the requested action.
Examples:
- credential is not enabled for Pricing API v1
- credential owner is not supported for Pricing API v1
Example:
{
"error": {
"code": "credentials_not_enabled",
"message": "Credentials are not enabled for Pricing API v1"
}
}
Use credential_owner_unsupported when the credential owner type is not
supported by Pricing API v1.
404 Not Found
Return 404 Not Found with not_found for an unknown Pricing API v1 route.
405 Method Not Allowed
Return 405 Method Not Allowed with method_not_allowed when a route exists
but does not support the request method.
406 Not Acceptable
Return 406 Not Acceptable when the request's Accept header does not permit
an application/json response.
{
"error": {
"code": "not_acceptable",
"message": "Accept header must be application/json"
}
}
500 Internal Server Error
Return 500 Internal Server Error with pricing_configuration_error when
ScriptDrop cannot resolve the pricing configuration or rating context for the
authenticated caller. Return internal_error for an unexpected server-side
failure.
Example:
{
"error": {
"code": "pricing_configuration_error",
"message": "Pricing is not configured for this caller"
}
}
502 Bad Gateway
Return 502 Bad Gateway when ScriptDrop cannot obtain a USPS pricing quote.
{
"error": {
"code": "pricing_provider_unavailable",
"message": "Pricing provider unavailable"
}
}
503 Service Unavailable
Return 503 Service Unavailable when ScriptDrop has temporarily paused Pricing
API v1. Authentication is checked before this response, so invalid credentials
continue to receive 401 Unauthorized.
{
"error": {
"code": "pricing_temporarily_unavailable",
"message": "Pricing API is temporarily unavailable"
}
}
422 Unprocessable Content
Return 422 Unprocessable Content with validation_failed when a request is
valid JSON but violates Pricing API request validation. The response includes
fields for each invalid input.
Example:
{
"error": {
"code": "validation_failed",
"message": "Validation failed",
"fields": {
"pickup.address.zipcode": ["must be a valid ZIP5"]
}
}
}