NAV
elixir shell

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 OK response 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:

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:

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"]
    }
  }
}