Introduction

The main purpose of this Goods API Documentation site is provide proper information and examples on how to operate with ship-from-store deliveries and returns via Goods.

The Goods API is organized around REST and has predictable resource-oriented URLs, uses standard HTTP response codes and authentication. Our API accepts form-encoded request bodies and returns JSON-encoded responses.

Getting Started

🔑 Remember before you can get started you need a **valid authorization token.**

Please email us at api@goodsdelivery.io, so we can issue you valid credentials asap. Remember when reaching out please provide any relevant information including the brands you’re representing for further validation.

Open API

You can download an OpenAPI file that defines our API from this link. Feel free to use it to generate an API client or check some details of our API. Read more about OpenAPI at https://www.openapis.org/

Authentication

API requests will result in 401 Unauthorized if your account specific credentials are not present in the request. API credentials should be included in your request using the x-api-key header. We will send you the API key value that will be ready to use in your requests.

Environments

We have two available environments: Sandbox and Production. In this section, we will detail how to get set up in each.

Sandbox

Our Sandbox environment allows you to test your integration with simulated courier bots which mimic real-life deliveries.

Base URL: https://api-sandbox.goodsdelivery.io

Although the integration is hopefully fairly straight-forward, we’re more than happy to support and be hands-on while you’re working on the integration. Please feel free to reach out to niels.thomsen@goodsdelivery.io for any questions you may have, or suggest any times for an online call for help and guidance.

Production

Once your integration is ready and the agreement with Goods has been signed, you can move the Production environment to start requesting Goods deliveries and returns in the real world.

Base URL: https://api.goodsdelivery.io

Common Use Cases

• Get a quote to see eligibility and associated rates
• Create a ship-from-store delivery
• Create a return pick-up request
• Retrieve a list of supported ZIP-codes
• Retrieve information and see the status of an existing delivery
• Setup a webhook when a delivery status updates

Jobs

A job represents either a delivery or a return and is the principal object that you’ll work with. Each job has a pick-up address and a drop-off address. Once created, a job may go through the following status updates which can be observed through the Goods tracking application, Merchant Dashboard, through real-time webhook updates, or through the Get a delivery API endpoint.

****Happy Path Job Statuses****

Code	Description
SCHEDULED	Job scheduled
OUT_FOR_PICKUP	Out for pick-up
PICKED_UP	Has been picked-up at the pick-up address
AT_HUB	At our hub for sorting
OUT_FOR_DROP_OFF	Out for drop-off
COMPLETED	Job has been completed

****Edge Case Job Statuses****

Code	Description
PICK_UP_FAILED	A courier wasn’t able to pick-up the job a the pick-up location. We’ll do a total of 3 attempts, before the job will be marked completed with a failed reason.
DROP_OFF_FAILED	A courier wasn’t able to drop-off the job a the defined drop-off location. We’ll do a total of 3 attempts, before we’ll return the job to the store.
OUT_FOR_RETURN	The job is out for return to the store after 3 failed drop-off attempts. Afterwards the job will be marked as completed with a failed reason.

Postman Collection

You can run our API in Postman by using our postman collection, which will help you play around with our API endpoints before starting the actual integration work. Click here to run our API in Postman.

Sequence Diagram

A sequence diagram can various from brand to brand depending on the use cases, however below we’ve create a few simple sequence diagrams of the most common use cases.

Creation of a ship-from-store delivery:

Creation of a return pick-up: