SERA uses the industry-standard OAuth 2.0 protocol for authentication. Completing the authentication procedure for access to SERA requires a few steps.

1. Login: Application presents the server-hosted login page to the user in a browser.
2. Redirect with Authorization Code: Once the user logs in and authorizes the application, an authorization code is returned to the application.
3. Initial Token Generation: Application uses authorization code to generate the initial set of access and refresh tokens.
4. Refresh Token: Application uses the stored refresh token to generate a new access token as needed.

Login

Integrators will present the server-hosted login page to the user by displaying the /authorize page with query parameters set specific to their integration. These query parameters include the following:

• response_type = code
• client_id = value specific to individual application/integration
• redirect_uri = value specific to individual application/integration
• scope = offline_access (required to receive a refresh token)

Redirect with Authorization Code

The redirect URI must be set to a location that the application can receive the authorization code from. The specific value will depend on the type of application that is being developed.

• Web applications can set up a callback page to receive the code query parameter.
• Native applications have a few different options to receive the authorization code.
  • If the application is displaying the login page in an embedded web browser control, the application can extract the code query parameter value from the control's current location/URL on successful login.
  • If the application is opening the login page using a web browser application, it can receive the code either by
    • hosting a temporary local web server to receive the code (redirecting the user to http://localhost:12345/ for example) or
    • registering a custom application handler with the OS to pass the code back to the application (redirecting the user to myapp://callback/ for example, where myapp:// is configured to call the integrated application).

In any case, the redirect_uri value specific to an application must be provided in advance in order to setup a valid Client ID for use in connecting to SERA.

Initial Token Generation

Once the integrated application has a valid authorization code, it must immediately use it to call the /oauth/token endpoint for an access_token and refresh_token. While both tokens should be stored securely and confidentially, the access_token is stored for a short amount of time while the refresh_token is stored for long-term access.

The application can begin calling SERA using the access_token value in the Authorization header preceded by the word Bearer as below.

Authorization: Bearer xyz123abc987....

Refresh Token

A valid access_token is required for every SERA call and is expected to regularly expire. Once an access_token has expired or is near-expiration, the integration should used the stored refresh_token to call for a new access_token by calling the /oauth/token endpoint again.

After completing the authentication process and receiving an access_token, integrators should call GET /account. The information returned is useful for an integration to configure default addresses and application capabilities.

Integrations should be aware of the user's account balance when initiating SERA transactions. The user's real-time account balance is available by calling GET /v1/balance. If the user's account balance is insufficient to cover a requested transaction, funds should be added to the account balance by calling POST /v1/balance/add-funds with the desired amount to add.

Before printing a label, users can call the POST /rates  endpoint to search and compare different rates for a shipment. A specific rate can then be selected for use from the returned rate options when creating a label in the next step.

The POST /rates endpoint produces a list of available rates. To narrow down the resultant list, this endpoint accepts optional information about a shipment such as the To and From addresses, as well as the package weight, type, and dimensions. Rates will vary by carrier and service_type (for example, using service_type ups_standard to receive rates for UPS Standard). Rates can also be further customized with advanced_options such as Signature Confirmation or Insurance.

If searching for a specific rate, try to include as many details as possible in the initial request. This way the returned list of available rates will be more closely tailored to the shipper’s needs. To receive an unfiltered list of available rates, try omitting any package specific information. In the following example, only the origin and destination ZIP code, package type, and package weight are provided. Try modifying the example call to reflect a specific set of shipment details and avoid errors by ensuring the ship_date is set to a date that is not in the past.

Request

{
  "from_address": {
    "postal_code": "92802"
  },
  "to_address": {
    "postal_code": "32830"
  },
  "package": {
    "packaging_type": "large_envelope",
    "weight": 24,
    "weight_unit": "ounce"
  },
  "ship_date": "{{$isoTimestamp}}"
}

Response

[
  {
    "carrier": "usps",
    "service_type": "usps_priority_mail",
    "packaging_type": "large_envelope",
    "estimated_delivery_days": "2",
    "estimated_delivery_date": "2021-09-07T21:30:14.226Z",
    "is_guaranteed_service": false,
    "trackable": "yes",
    "is_return_label": false,
    "is_customs_required": false,
    "shipment_cost": {
      "total_amount": 11.69,
      "currency": "usd",
      "cost_details": [
        {
          "fee_code": "usps_priority_mail",
          "fee_type": "service",
          "amount": 11.69
        }
      ]
    }
  },
  {
    "carrier": "usps",
    "service_type": "usps_priority_mail_express",
    "packaging_type": "large_envelope",
    "estimated_delivery_days": "1-2",
    "estimated_delivery_date": null,
    "is_guaranteed_service": true,
    "trackable": "yes",
    "is_return_label": false,
    "is_customs_required": false,
    "shipment_cost": {
      "total_amount": 45.7,
      "currency": "usd",
      "cost_details": [
        {
          "fee_code": "usps_priority_mail_express",
          "fee_type": "service",
          "amount": 45.7
        }
      ]
    }
  },
  {
    "carrier": "usps",
    "service_type": "usps_media_mail",
    "packaging_type": "large_envelope",
    "estimated_delivery_days": "7",
    "estimated_delivery_date": "2021-09-13T21:30:14.226Z",
    "is_guaranteed_service": false,
    "trackable": "yes",
    "is_return_label": false,
    "is_customs_required": false,
    "shipment_cost": {
      "total_amount": 3.82,
      "currency": "usd",
      "cost_details": [
        {
          "fee_code": "usps_media_mail",
          "fee_type": "service",
          "amount": 3.82
        }
      ]
    }
  }
]

As described in Viewing Shipping Rates, there are many options available for both domestic and international labels. Once a specific rate has been selected from these available options, the rate details can be included in the request to POST /labels in order to purchase the shipping label.

The following examples will cover both a simple domestic USPS shipping label using only the required and most common request settings, as well as an international label for a basic USPS First Class International shipment to Canada. There are many other ways to configure a label request, including advanced_options or different image formats and label layouts. For further details, see the Create a Label section in the reference guide.

Note that default values will be used for any optional elements omitted from a label creation request.

Create a Domestic Label

1. Input sample domestic shipment details into the label generation request. The example provided can be used. For further details on this request, see the Create a Label section
2. Notable request elements:
   • The from_address must contain the name or company_name, address_line1, city,state_province, and postal_code.
3. After executing the sample request, a response should be returned containing an array of labels, each with an href field containing a URL. Fetch that URL in a browser to see the final shipping label.

Create an International Label

1. Input sample international shipment details into the label generation request. The example provided can be used. For further details on this request, see the Create a Label section . This is very similar to domestic label creation, one of the main differences being the inclusion of Customs information in the customs object for international.3. Notable request elements:
   • The from_address must contain the name or company_name, address_line1, city,state_province, and postal_code.
   • The customs object contains a description of what is being shipped. International shipments require Customs information and will be submitted electronically to the carrier in addition to being printed with your label if required.
2. After executing the sample request, a response should be returned containing an array of labels, each with an href field containing a URL. Fetch that URL in a browser to see the final shipping label.

Request

{
  "from_address": {
    "name": "Michael M",
    "address_line1": "1150 Magic Way",
    "city": "Anaheim",
    "state_province": "CA",
    "postal_code": "92802",
    "country_code": "US",
    "email": "[email protected]"
  },
  "to_address": {
    "name": "Minerva M",
    "address_line1": "351 S Studio Dr",
    "city": "Lake Buena Vista",
    "state_province": "FL",
    "postal_code": "32830",
    "country_code": "US",
    "email": "[email protected]"
  },
  "service_type": "usps_priority_mail",
  "package": {
    "packaging_type": "package",
    "weight": 4,
    "weight_unit": "ounce"
  },
  "ship_date": "2021-09-10",
  "is_test_label": true
}

Response

{
  "label_id": "13bab305-a5eb-4ad6-a1d2-e5b545e764fb",
  "tracking_number": "9405511899560772485630",
  "carrier": "usps",
  "service_type": "usps_priority_mail",
  "packaging_type": "package",
  "estimated_delivery_days": "2",
  "estimated_delivery_date": "2021-09-13T00:00:00",
  "is_guaranteed_service": false,
  "trackable": "yes",
  "is_return_label": false,
  "is_gap": false,
  "is_smartsaver": false,
  "is_etoe": false,
  "shipment_cost": {
    "total_amount": 8.8,
    "currency": "usd",
    "cost_details": [
      {
        "fee_code": "usps_priority_mail",
        "fee_type": "service",
        "amount": 8.8
      },
      {
        "fee_code": "tracking",
        "fee_type": "tracking",
        "amount": 0
      }
    ]
  },
  "account_balance": {
    "amount_available": 390.65,
    "max_balance_amount_allowed": 10000,
    "currency": "usd"
  },
  "labels": [
    {
      "href": "<LabelURL>"
    }
  ],
  "forms": null,
  "branding_id": null,
  "notification_setting_id": null
}

If a user wishes to request a refund for any unused prepaid labels, the PUT /labels/{label_id}/void endpoint can be called to cancel the label. The carrier may need to verify that the label was not used in order to authorize the refund. As a result, it may take 2–3 weeks to approve a refund request.

To create a refund request, call the PUT /labels/{label_id}/void endpoint with a valid label_id (as returned in the original label's response) in the URL which represents the label to be cancelled. Pay-On-Use labels are not eligible to be cancelled.

Note that test labels created in the staging environment do not need to be cancelled and are printed with a visible "VOID" message over the label image.

Sometimes an integration may need to explicitly request address validation. For example, there may be cases where SERA could not automatically validate the address during the label creation process. An address can be submitted to the POST /addresses/validate endpoint to perform this validation. The address validation results will then be returned along with any applicable candidate addresses. These candidate addresses can then be reviewed, and a correct address can be selected for use in shipping by the user or application.

It is best practice to fully validate addresses used for shipping in order to minimize package delivery issues. Note that a validated city, state, and postal code are required when shipping domestically.

Request

[
  {
    "address_line1": "4800 Third Ave",
    "city": "Kearney",
    "state_province": "NE",
    "postal_code": "68845",
    "country_code": "US",
    "email": null
  }
]

Response

[
  {
    "original_address": {
      "company_name": null,
      "name": null,
      "address_line1": "4800 Third Ave",
      "address_line2": null,
      "address_line3": null,
      "city": "Kearney",
      "state_province": "NE",
      "postal_code": "68845",
      "country_code": "US",
      "phone": null,
      "email": null,
      "residential_indicator": null,
      "formatted_address": null
    },
    "matched_address": {
      "company_name": null,
      "name": null,
      "address_line1": "4800 3RD AVE",
      "address_line2": "",
      "address_line3": null,
      "city": "KEARNEY",
      "state_province": "NE",
      "postal_code": "68845-2892",
      "country_code": "US",
      "phone": null,
      "email": null,
      "residential_indicator": "no",
      "formatted_address": "4800 3RD AVE\nKEARNEY, NE 68845-2892"
    },
    "candidate_addresses": [],
    "is_po_box": false,
    "is_apo_fpo": false,
    "validation_results": {
      "result_code": "V100",
      "result_description": "Full Address Verified.",
      "result_details": null
    }
  }
]

There may also be scenarios where an application needs to explicitly request address parsing, such as when only a freeform address string is provided. A freeform address string can be submitted to the POST /addresses/parse endpoint to parse it into a formatted address. The formatted address will then be returned along with the address fields the parser was able to populate. This parsed address can then be passed to the POST /addresses/validate endpoint to validate the address if needed.

Request

{
  "full_address": "Jeff Moreau 7700 W Parmer Ln Unit 250 Austin Tx 78729"
}

Response

{
  "company_name": null,
  "name": "Jeff Moreau",
  "address_line1": "7700 W Parmer Ln Unit 250",
  "address_line2": "",
  "address_line3": null,
  "city": "Austin",
  "state_province": "TX",
  "postal_code": "78729-8101",
  "country_code": "US",
  "phone": null,
  "email": null,
  "residential_indicator": null,
  "formatted_address": "7700 W Parmer Ln Unit 250\nAustin, TX 78729-8101"
}

After shipping a package, most integrators also need to periodically check on the status of a package. The GET /tracking endpoint returns tracking events for any shipment created through Stamps.com/Endicia. Include a label_id or tracking_number in the request to specify the label to track.

The response will consist of an array of tracking_event objects with timestamps for each event.

In order to access SERA, integrations must call the API with a valid access token. Access tokens can be generated with a valid authorization code from a user's login event or with an refresh token from an earlier login. The endpoints below detail how to login to receive an authorization code and how to turn that code into a valid set of access and refresh tokens.

SERA labels and services are paid for with an account balance. Funds are added to the account balance from the account’s default payment method, while transaction amounts for labels and services are deducted from the account balance. While most customers utilize credit cards to fund their accounts balances, we do offer alternative payment methods such as ACH on request.

Most labels are deducted from the account balance at time of print. We also offer Pay-On-Use services (e.g. USPS Returns) that deduct from the account balance when the label is shipped instead of when it is created. New accounts are limited to a maximum balance of $500 which can be adjusted by contacting our customer care team.