shipengine/shipengine-openapi

The official OpenAPI 3.0 definitions for ShipEngine™

ShipEngine™ OpenAPI Definition

This repo contains the official OpenAPI 3.0 definitions for the ShipEngine API. You can use these definitions with any of countless OpenAPI tools to generate sample code, tests, mock servers, etc.

Which file to use

Depending on your preferences and/or tooling, you may choose to use one or more of the following files:

Path	Description
openapi.yaml	The entire ShipEngine OpenAPI definition, in a single YAML file. This file uses $ref pointers to reduce duplication and keep the file small and fairly human-readable. Some OpenAPI tools don't support YAML or don't support $ref pointers, so you may need to use the openapi.json file instead.
openapi.json	The entire ShipEngine OpenAPI definition, in a single JSON file. This file does not contain any $ref pointers, which means it should work with any OpenAPI tool.

Other API Definition Formats

View the ShipEngine API definition online in your browser. This web page is generated from the OpenAPI definition using ReDoc.

Postman

The official Postman reference collection for ShipEngine. Just import it into Postman and immediately begin interacting with the ShipEngine API.

New to ShipEngine? Download our walkthrough collection instead.

JSON Schema

If you need to validate API requests and responses, then you may want to use our JSON Schema definitions.

shipengine-openapi's Issues

Missing label_image_id for getting labels from rates

This was not documented so I added it to the OpenAPI XML spec and also added it to our C# client library. The issue in question is here:

kendallb/ShipEngineApi#1

You should pull my change over from my fork, but also have the documentation on the web site updated based on what support sent to the other developer?

https://www.shipengine.com/docs/labels/create-from-rate/

Support OpenAPI tools that don't fully support additionalProperties

It appears it is not working with SwaggerHub (I have opened a ticket with them), but it also does not work with AutoRest. When I run it with AutoRest I see the following, which seems to indicate something is broken in the configuration?

C:\src\snap\DataAccess\Modules\Shipping\ShipEngineClient>autorest config.yaml
AutoRest code generation utility [cli version: 3.0.6187; node: v12.18.3, max-memory: 8192 gb]
(C) 2018 Microsoft Corporation.
https://aka.ms/autorest
   Loading AutoRest core      'C:\Users\kenda\.autorest\@[email protected]\node_modules\@autorest\core\dist' (3.0.6306)
   Loading AutoRest extension '@microsoft.azure/autorest.csharp' (~2.3.79->2.3.84)
   Loading AutoRest extension '@microsoft.azure/autorest.modeler' (2.3.55->2.3.55)
FATAL: Error parsing swagger file. Error converting value False to type 'AutoRest.Modeler.Model.Schema'. Path 'components.schemas.parse_address_request_body.additionalProperties', line 1, position 109890.
FATAL: AutoRest.Core.Logging.CodeGenerationException: Error parsing swagger file. Error converting value False to type 'AutoRest.Modeler.Model.Schema'. Path 'components.schemas.parse_address_request_body.additionalProperties', line 1, position 109890.
   at AutoRest.Modeler.SwaggerParser.Parse(String swaggerDocument) in /opt/vsts/work/1/s/src/SwaggerParser.cs:line 52
   at AutoRest.Modeler.Program.<ProcessInternal>d__2.MoveNext() in /opt/vsts/work/1/s/src/Program.cs:line 58
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at NewPlugin.<Process>d__15.MoveNext()
  Error: Plugin imodeler1 reported failure.

Name and Phone Fields On Address Model Should Not Be Required

In the openapi.yaml, the name and phone fields on the partial address model as well as the address model are not nullable. This creates a problem in the validate address operation. Below you can see that the operation does not require name or phone in the request body.

    address_to_validate:
      title: address_to_validate
      type: object
      description: |
        Any residential or business mailing address, anywhere in the world.
      required:
        - address_line1
        - city_locality
        - state_province
        - country_code
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/partial_address'

However, the response returns the original address, but the type for the original address is the address type which requires name and phone. See below.

    address:
      title: address
      type: object
      description: >
        Any residential or business mailing address, anywhere in the world.
        > **Note:** Either `name` or `company_name` must be set. Both may be
        specified, if relevant.
      required:
        - name  # <----- SHOULD NOT BE REQUIRED
        - phone # <----- SHOULD NOT BE REQUIRED
        - address_line1
        - city_locality
        - state_province
        - postal_code
        - country_code
        - address_residential_indicator
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/partial_address'

On the partial_address, the name and phone are not set to be nullable. Maybe they should.

    partial_address:
      title: partial_address
      type: object
      description: A complete or partial mailing address.
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          example: John Doe
          description: >
            The name of a contact person at this address.  This field may be set
            instead of - or in addition to - the `company_name` field.
         nullable: true # <---- MAYBE NEEDS TO BE NULLABLE
        phone:
          type: string
          minLength: 1
          nullable: true # <----  MAYBE NEEDS TO BE NULLABLE
          example: [phone] ext. 123
          description: >
            The phone number of a contact person at this address.  The format of
            this phone number varies depending on the country.

---

This error causes an issue when generating code for a strongly typed language or generating code with validation. The solution here is to make these fields not required or have separate address models.

OpenAPI Errors with OpenAPI Generator

I'm trying to generate a Go client with openapi-generator from the provided Open API JSON/YAML however the generator fails with 54 errors and 263 warnings. openapi-generator does have an option to skip validation but unfortunately these errors persist with generation.

Using the latest openapi.json in this repository, this is the command I'm using to attempt generating a client in Go:

openapi-generator generate -i shipengine-openapi/openapi.json -g go -o ./client

Output

Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 54, Warning count: 263
Errors:
	-attribute paths.'/v1/relay_points'(get).parameters.[city_locality].minLength is unexpected
	-attribute paths.'/v1/shipments/{shipment_id}'(put).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/shipments/recognize'(put).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/labels/shipment/{shipment_id}'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.shipment.properties is not of type `object`
	-attribute paths.'/v1/shipments'(post).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.get_shipment_by_id_response_body.properties is not of type `object`
	-attribute paths.'/v1/labels/{label_id}'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/shipments/external_shipment_id/{external_shipment_id}'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/rates'(post).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.create_label_response_body.properties is not of type `object`
	-attribute paths.'/v1/shipments'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.address_validating_shipment.properties is not of type `object`
	-attribute components.schemas.parse_shipment_response_body.properties is not of type `object`
	-attribute paths.'/v1/labels/{label_id}/return'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/shipments'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.calculate_rates_response_body.properties is not of type `object`
	-attribute components.schemas.label.properties is not of type `object`
	-attribute paths.'/v1/labels/rates/{rate_id}'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/labels'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/labels'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.create_label_request_body.properties is not of type `object`
	-attribute components.schemas.create_shipments_request_body.properties is not of type `object`
	-attribute components.schemas.get_label_by_id_response_body.properties is not of type `object`
	-attribute paths.'/v1/shipments/recognize'(put).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.get_shipment_by_external_id_response_body.properties is not of type `object`
	-attribute components.schemas.package.properties is not of type `object`
	-attribute components.schemas.Schema name manifests requests doesn't adhere to regular expression ^[a-zA-Z0-9\.\-_]+$
	-attribute paths.'/v1/labels'(post).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.Schema name manifest request doesn't adhere to regular expression ^[a-zA-Z0-9\.\-_]+$
	-attribute components.schemas.compare_bulk_rates_request_body.properties is not of type `object`
	-attribute components.schemas.create_shipments_response_body.properties is not of type `object`
	-attribute paths.'/v1/relay_points'(get).parameters.[service_code].minLength is unexpected
	-attribute components.schemas.list_labels_response_body.properties is not of type `object`
	-attribute paths.'/v1/relay_points'(get).parameters.[postal_code].minLength is unexpected
	-attribute components.schemas.create_label_from_rate_response_body.properties is not of type `object`
	-attribute paths.'/v1/relay_points'(get).parameters.[country_code].minLength is unexpected
	-attribute components.schemas.update_shipment_request_body.properties is not of type `object`
	-attribute components.schemas.calculate_rates_request_body.properties is not of type `object`
	-attribute components.schemas.shipment_request.properties is not of type `object`
	-attribute components.schemas.get_label_by_external_shipment_id_response_body.properties is not of type `object`
	-attribute paths.'/v1/shipments/{shipment_id}'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.create_and_validate_shipment.properties is not of type `object`
	-attribute paths.'/v1/rates'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/rates/bulk'(post).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.partial_shipment.properties is not of type `object`
	-attribute components.schemas.rate_request_by_shipments.properties is not of type `object`
	-attribute paths.'/v1/labels/external_shipment_id/{external_shipment_id}'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.create_label_from_shipment_response_body.properties is not of type `object`
	-attribute components.schemas.list_shipments_response_body.properties is not of type `object`
	-attribute components.schemas.parse_shipment_request_body.properties is not of type `object`
	-attribute paths.'/v1/shipments/{shipment_id}'(put).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.create_return_label_response_body.properties is not of type `object`
	-attribute components.schemas.update_shipment_response_body.properties is not of type `object`
Warnings:
	-attribute paths.'/v1/relay_points'(get).parameters.[city_locality].minLength is unexpected
	-attribute paths.'/v1/shipments/{shipment_id}'(put).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/shipments/recognize'(put).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/labels/shipment/{shipment_id}'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.shipment.properties is not of type `object`
	-attribute paths.'/v1/shipments'(post).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.get_shipment_by_id_response_body.properties is not of type `object`
	-attribute paths.'/v1/labels/{label_id}'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/shipments/external_shipment_id/{external_shipment_id}'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/rates'(post).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.create_label_response_body.properties is not of type `object`
	-attribute paths.'/v1/shipments'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.address_validating_shipment.properties is not of type `object`
	-attribute components.schemas.parse_shipment_response_body.properties is not of type `object`
	-attribute paths.'/v1/labels/{label_id}/return'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/shipments'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.calculate_rates_response_body.properties is not of type `object`
	-attribute components.schemas.label.properties is not of type `object`
	-attribute paths.'/v1/labels/rates/{rate_id}'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/labels'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/labels'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.create_label_request_body.properties is not of type `object`
	-attribute components.schemas.create_shipments_request_body.properties is not of type `object`
	-attribute components.schemas.get_label_by_id_response_body.properties is not of type `object`
	-attribute paths.'/v1/shipments/recognize'(put).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.get_shipment_by_external_id_response_body.properties is not of type `object`
	-attribute components.schemas.package.properties is not of type `object`
	-attribute components.schemas.Schema name manifests requests doesn't adhere to regular expression ^[a-zA-Z0-9\.\-_]+$
	-attribute paths.'/v1/labels'(post).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.Schema name manifest request doesn't adhere to regular expression ^[a-zA-Z0-9\.\-_]+$
	-attribute components.schemas.compare_bulk_rates_request_body.properties is not of type `object`
	-attribute components.schemas.create_shipments_response_body.properties is not of type `object`
	-attribute paths.'/v1/relay_points'(get).parameters.[service_code].minLength is unexpected
	-attribute components.schemas.list_labels_response_body.properties is not of type `object`
	-attribute paths.'/v1/relay_points'(get).parameters.[postal_code].minLength is unexpected
	-attribute components.schemas.create_label_from_rate_response_body.properties is not of type `object`
	-attribute paths.'/v1/relay_points'(get).parameters.[country_code].minLength is unexpected
	-attribute components.schemas.update_shipment_request_body.properties is not of type `object`
	-attribute components.schemas.calculate_rates_request_body.properties is not of type `object`
	-attribute components.schemas.shipment_request.properties is not of type `object`
	-attribute components.schemas.get_label_by_external_shipment_id_response_body.properties is not of type `object`
	-attribute paths.'/v1/shipments/{shipment_id}'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.create_and_validate_shipment.properties is not of type `object`
	-attribute paths.'/v1/rates'(post).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute paths.'/v1/rates/bulk'(post).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.partial_shipment.properties is not of type `object`
	-attribute components.schemas.rate_request_by_shipments.properties is not of type `object`
	-attribute paths.'/v1/labels/external_shipment_id/{external_shipment_id}'(get).responses.200.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.create_label_from_shipment_response_body.properties is not of type `object`
	-attribute components.schemas.list_shipments_response_body.properties is not of type `object`
	-attribute components.schemas.parse_shipment_request_body.properties is not of type `object`
	-attribute paths.'/v1/shipments/{shipment_id}'(put).requestBody.content.'application/json'.schema.properties is not of type `object`
	-attribute components.schemas.create_return_label_response_body.properties is not of type `object`
	-attribute components.schemas.update_shipment_response_body.properties is not of type `object`

	at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:556)
	at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:583)
	at org.openapitools.codegen.cmd.Generate.execute(Generate.java:433)
	at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
	at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

Open Api errors with openapi-typescript

Hi, I wanted to generate types from the provided yaml using openapi-typescript with this command:
openapi-typescript node_modules/shipengine-openapi/openapi.yaml --output src/types/ShipEngineTypes.ts

However, three types seem to have an issue, though not sure on the exact cause

• pickup_response_body
• get_rate_by_id_response_body
• update_shipment_response_body

type and error for update_shipment_response_body

update_shipment_response_body: WithRequired<components["schemas"]["create_and_validate_shipment"], "errors" | "has_errors" | "address_validation" | "shipment_id" | "carrier_id" | "service_code" | "ship_date" | "created_at" | "shipment_status" | "ship_to" | "ship_from" | "return_to" | "confirmation" | "customs" | "advanced_options" | "insurance_provider" | "tags" | "packages" | "total_weight">;

Type '"created_at" | "ship_date" | "shipment_id" | "carrier_id" | "service_code" | "shipment_status" | "ship_to" | "ship_from" | "return_to" | "confirmation" | "customs" | "advanced_options" | ... 6 more ... | "address_validation"' does not satisfy the constraint '"created_at" | "modified_at" | "ship_date" | "shipment_id" | "carrier_id" | "service_code" | "shipment_status" | "ship_to" | "ship_from" | "warehouse_id" | "return_to" | "confirmation" | ... 15 more ... | "address_validation"'.
  Type '"has_errors"' is not assignable to type '"created_at" | "modified_at" | "ship_date" | "shipment_id" | "carrier_id" | "service_code" | "shipment_status" | "ship_to" | "ship_from" | "warehouse_id" | "return_to" | "confirmation" | ... 15 more ... | "address_validation"'.ts(2344)

type and error for get_rate_by_id_response_body

get_rate_by_id_response_body: WithRequired<components["schemas"]["rate"], "rates" | "invalid_rates" | "rate_request_id" | "shipment_id" | "created_at" | "status" | "errors">;

Type '"shipment_id" | "created_at" | "errors" | "rates" | "invalid_rates" | "rate_request_id" | "status"' does not satisfy the constraint '"carrier_id" | "service_code" | "ship_date" | "carrier_code" | "estimated_delivery_date" | "package_type" | "requested_comparison_amount" | "trackable" | "rate_type" | "validation_status" | ... 15 more ... | "error_messages"'.
  Type '"shipment_id"' is not assignable to type '"carrier_id" | "service_code" | "ship_date" | "carrier_code" | "estimated_delivery_date" | "package_type" | "requested_comparison_amount" | "trackable" | "rate_type" | "validation_status" | ... 15 more ... | "error_messages"'.ts(2344)

I thought it could be an issue with required fields, for example from the yaml:

    get_rate_by_id_response_body:
      title: get_rate_by_id_response_body
      type: object
      description: A rate response body
      required:
        - rates
        - invalid_rates
        - rate_request_id
        - shipment_id
        - created_at
        - status
        - errors

in this case I'm not sure if rates should be required for Get Rate By Id which should only be returning one rate based on https://shipengine.github.io/shipengine-openapi/#operation/get_rate_by_id

or in the case of pickup_response_body, pickup is required in addition to all the properties of "pickup" such as pickup_id

pickup_response_body:
      title: pickup_response_body
      type: object
      description: A pickup response body
      required:
        - pickup
        - pickup_id
        - label_ids
        - created_at
        - carrier_id
        - warehouse_id
        - pickup_address
        - contact_details
        - notes
        - pickup_window
        - confirmation_number
      additionalProperties: false
      allOf:
        - $ref: '#/components/schemas/pickup'

API Spec has invalid model name

The "rate estimate" model in the API Spec has an invalid model name, it should be "rate_estimate" instead. This is preventing auto generating API clients.

https://github.com/ShipEngine/shipengine-openapi/blob/master/openapi.yaml#L9258

    rate estimate:
      title: rate estimate
      type: object
      description: A rate estimate
      required:

Error trying to generate API Client with swagger.json

HI,
I'm using NSwagStudio v 13.15.10.0
I downloaded swagger.json from https://shipengine.github.io/shipengine-openapi/
There were errors in the file,
Line 9333 and Line 12027

Could you please try to check by test generating a client with what you guy provided?
Thank you
Art

You should not insert new entries in the middle of enumerations?

Ok, anyone who uses these API definitions to generate API code in strongly typed languages like C# or Java will end up with an enumeration for the 'error_code' field. We had a breakage yesterday when some of the carriers started returning new error values that were not defined in the spec so the resulting payload would fail to parse.

We reached out to support and the 'fix' is this commit:

e3e74cb

Which just adds the new errors to the enumeration. But that does not help anyone who has pre-compiled libraries as we all need to rebuild against the new spec. But worse, since you just inserted new values into the error table in the middle of the table, any existing binary values that represent those values when generated by an API will no longer be compatible.

Honestly it's just not a good idea to add new fields to enumerations as defined in the spec as you will break folks code running out in the wild.

Update carrier settings - inconsistent carrier_name

Hello, I found an inconsistency with the API / Documentation.

https://github.com/ShipEngine/shipengine-openapi/blob/master/openapi.yaml#L1101

Documentation says settings endpoint supports stamps_com which I believe is correct, however, requesting this endpoint I receive the following error:

{
    "request_id": "1ca82945-e86f-47f1-b585-1f849a68ea62",
    "errors": [
        {
            "error_source": "shipengine",
            "error_type": "security",
            "error_code": "not_found",
            "message": "POST",
            "method": "/v1/connections/carriers/stamps_com/se-284845/settings",
            "path": "POST /v1/connections/carriers/stamps_com/se-284845/settings is not a valid API endpoint.",
        }
    ]
}

So it looks like its more of an API issue than a documentation issue, I'm just not sure where to post the API issue.

Changing it to stamps-com allows the request to continue further (although still receiving a 500 server error).

Validate address endpoint violates the partial_address model validation

When calling the address validation endpoint it will sometimes respond with address_line2 of the matched address value set to an empty string instead of a null value. The partial_address model requires the address_line2 value be null or have a length > 0. This is causing issues with auto generated client libraries.

Rule:

        address_line2:
          type: string
          minLength: 1
          nullable: true
          example: Unit 408
          description: >
            The second line of the street address.  For some addresses, this
            line may not be needed.

Response:

[
  {
    "status": "verified",
    "original_address": {
      "name": "REDACTED",
      "phone": null,
      "company_name": null,
      "address_line1": "REDACTED",
      "address_line2": null,
      "address_line3": null,
      "city_locality": "REDACTED",
      "state_province": "REDACTED",
      "postal_code": "REDACTED",
      "country_code": "US",
      "address_residential_indicator": "unknown"
    },
    "matched_address": {
      "name": "REDACTED",
      "phone": null,
      "company_name": null,
      "address_line1": "REDACTED",
      "address_line2": "",
      "address_line3": null,
      "city_locality": "REDACTED",
      "state_province": "REDACTED",
      "postal_code": "REDACTED",
      "country_code": "US",
      "address_residential_indicator": "yes"
    },
    "messages": []
  }
]