Integrators call this endpoint to receive a 302 redirect to a hosted HTML login page. Once the user completes the login page, they will be redirected to the URL specified in redirect_uri with an authorization code contained in the code query parameter. For example, if the redirect_uri is "https://www.stamps.com", the user will be directed to "https://www.stamps.com/?code=<AuthorizationCode>" on successful login. Use this authorization code to generate an access_token.

Integrators call this endpoint with a valid authorization code or refresh_token and use the access_token from the response to access SERA.

This endpoint will return account information associated with the active user account.

The current account balance can be checked by calling this endpoint with no request body. The response will contain the account’s current balance.

To add funds to the account balance, call this endpoint with the amount you wish to add in the request body. A successful response will contain the current balance on the account.

In the SERA production environment, adding funds to the account balance will charge the account’s default payment method. In contrast, funds added in the SERA staging environment will not cost anything; staging account balances are funded with "play money."

There are several account management operations that are available to Stamps.com/Endicia users. Rather than duplicate that functionality in the form of API access, creating an additional burden on integrators to create the interface for it, SERA allows the integrator to obtain the URL of Stamps.com/Endicia-hosted web pages to perform these operations. Call this endpoint with a specific url_type query parameter to receive the URL of the hosted page.

The URLs returned from this endpoint are specific to the user and session, allowing the web interface to display information tailored for the user without requiring the user to re-authenticate. The URL is only valid for one request, so the URL should be immediately navigated to in a browser and not stored by the integration.

URLs to the following Stamps.com web pages are available through this web method: Home, Account Settings, Edit Cost Codes, Online Reports, and Help.

Through special arrangement, the Stamps.com/Endicia-hosted pages may be co-branded for the integrator. When this is done, an optional query parameter, application_context, may be included to customize the appearance and behavior of the hosted web page.

Call this endpoint to set security questions for an account that doesn't have them. Call GET /v1/security_questions to see the full list of available security questions.

Call this to see the full list of available security questions. To set security questions for an account that does not have them, call PUT /v1/account/security_questions

Rates contains all of a single shipment’s details, from origin and destination addresses to weight, carrier, and service options. Users can search for and compare different rates with calls to this SERA endpoint. In order to create a shipping label, a specific rate should be selected from the numerous available options and combinations.

This endpoint optionally accepts details about the shipment to narrow down the available rates. If available, add information such as the To and From addresses (or even just ZIP codes), along with package weight, type, and dimensions to the request body to receive a list of rates filtered for those attributes.

When searching for a specific rate, try to include as much information as possible in the initial request to receive a list of available rates more closely filtered to what is needed. If looking for a broad list of rates (for example, to populate a selection dialog), omit specific package information to receive an unfiltered list of available rates.

Using the response, it is up to the user or integration’s logic to select the desired rate. Once selected, the integration can use those rate details when creating a label. Rates will vary by carrier_code and service_code (such as "usps_priority_mail" for USPS Priority Mail) and may be further customized with any available advanced_options (such as Signature Confirmation or Insurance).

While testing, feel free to modify the example request to reflect various specific shipment details. Also, be sure to update the ship_date to a date that is not in the past or an error will be returned.

Once a specific rate is selected as described in View Shipping Rates, include the rate details in a request to this endpoint to purchase the shipping label.

For most labels, the rate amount will be deducted from the account balance when the label is created with this step. Be sure to have sufficient account balance for this before requesting the label or an error will be generated.

Users must void unused prepaid labels to request a refund. The carrier may need to verify the label was not used in order to authorize a refund. As a result, it may take 2–3 weeks to approve a refund request once submitted.

To request a refund, call this endpoint with a valid label_id (as returned in the original label's response) in the URL to identify the label to cancel. Pay-On-Use labels are not eligible to be voided.

To help improve package deliverability, it is best practice to fully validate all addresses used while shipping. While it’s not required that users ship to fully-validated addresses, it is required that users ship to addresses with at least partial validation: a validated city, state, and postal code are required when shipping domestically.

Occasionally, if SERA cannot automatically validate an address while creating a shipping label, the integration may need to explicitly request address validation. To do this, submit the address to this endpoint.

In the response, SERA will return the address validation status along with any applicable candidate addresses. The user or application should review the candidate addresses and select one for use in shipping if it is correct.

Call this endpoint with an existing label_id to request the label image or data of a previously-created label. This will allow for an application to implement reprint functionality. Users are allowed to specify new label options to make non-material modifications to the reprinted label.

Note users are only allowed to reprint labels originally printed from their user account.

Depending on the carrier, a printed manifest (also called a SCAN form for USPS) may be needed when shipping multiple packages at once. Users can generate a manifest one of two ways:

1. Submit a from_address and ship_date. SERA will collect any matching prints to generate a manifest for.
2. Submit a list of label_ids to generate a manifest for.

The response will contain URLs for printable manifests in the requested format.

Carrier pickups can be scheduled by calling this endpoint with a carrier_code and a preferred pickup time.

The response will contain pickup_window information along with information about the pickup request.

To cancel a carrier pickup, call this endpoint with the pickup_id in the URL. No request body is needed.

The status of your request will be returned in the response.

After shipping a package, most integrators also need to periodically check on the status of a package. This endpoint retrieves and returns standardized tracking events for a given shipment. Include a valid carrier_code and tracking_number in the request’s query string to select the appropriate shipment.

The response will consist of the shipment’s current status and a full array of tracking_events with timestamps for each event. Because SERA standardizes carrier tracking for our supported carriers, integrators do not need to do any extra work to retrieve or interpret tracking status information on a carrier-by-carrier basis.

Depending on the carrier and types of packages, a container label may be needed when shipping multiple packages at once in a container. Users can generate a container label two ways:

1. Submit a from_address and ship_date. SERA will collect any matching prints to generate a container label for.
2. Submit a list of label_ids to generate a container label for.

As carrier service availability may vary based on user accounts, integrations may call this endpoint to receive a JSON object detailing the specific services and service limitations to present to users.

Call this endpoint to connect your existing carrier account to SERA.

Call this endpoint to disconnect your existing carrier account from SERA.