> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/getting-started/get-started-with-esw/quick-start-guide.md).

# Quick start guide

Sandbox quick starts: authenticate, then run each core ESW API flow end to end.

Quick starts take you from credentials to a working sandbox call fast. Each one is a short, ordered walkthrough with copy-ready requests, the rules that cause the most first-call errors, and links to the full reference.

{% hint style="info" icon="message-bot" %}
**Building with an AI coding agent?** Point it at [AGENTS.md](https://developer.esw.com/agents.md) first. It covers environments, authentication, which calls are safe to run, and the per-API rules behind most first-call errors.
{% endhint %}

### Start here

1. Complete the [Authentication quick start](/getting-started/get-started-with-esw/quick-start-guide/authentication.md). Every flow below needs an access token.
2. Pick the flow that matches what you are building.

### Choose your flow

| I want to                                                      | Quick start                                                                                   | Scope                                                                                                                                           | You will call                                         |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Get a token and make my first authenticated call               | [Authentication](/getting-started/get-started-with-esw/quick-start-guide/authentication.md)   | Depends on the API                                                                                                                              | STS token endpoint                                    |
| Send a cart to ESW and take the shopper through payment        | [Checkout](/getting-started/get-started-with-esw/quick-start-guide/checkout.md)               | `checkout.preorder.api.all`                                                                                                                     | Call PreOrder; receive the Order Confirmation webhook |
| Create an order and manage fulfillment and cancellations       | [Order](/getting-started/get-started-with-esw/quick-start-guide/order.md)                     | `order.transaction.create.api.all`, `order.transaction.get.api.all`, `order.transaction.update.api.all`, and `order.transaction.cancel.api.all` | Order, LineItemActivity, OrderActivity                |
| Show shoppers localized prices                                 | [Pricing Advisor](/getting-started/get-started-with-esw/quick-start-guide/pricing-advisor.md) | `pricing.advisor.api.all`                                                                                                                       | MultiplierAdvice, StandardAdvice                      |
| Share my product catalog so duties and taxes can be calculated | [Customs Catalog](/getting-started/get-started-with-esw/quick-start-guide/customs-catalog.md) | `logistics.catalog.api.upload`                                                                                                                  | RetailerCatalog                                       |
| Tell ESW what is in each parcel and get shipping labels        | [Package](/getting-started/get-started-with-esw/quick-start-guide/package.md)                 | `logistics.package.api.all`                                                                                                                     | Create, retrieve, and update a package                |
| Confirm pick and pack from my 3PL warehouse system             | [Fulfillment](/getting-started/get-started-with-esw/quick-start-guide/fulfillment.md)         | Varies by client                                                                                                                                | PickPack/Confirm                                      |
| Create returns for shoppers                                    | [Returns](/getting-started/get-started-with-esw/quick-start-guide/returns.md)                 | `logistics.returns.api.all`                                                                                                                     | Outbound orders, orders, return orders                |

### Before you begin

ESW provides your credentials through a secure channel during setup. Have these ready:

* A sandbox `client_id` and `client_secret`
* Your `tenantCode`. The Package API uses your `brandCode` instead
* The scopes enabled for your client

### Conventions you will see across the quick starts

* **JSON over HTTPS.** ESW APIs use resource-oriented URLs and JSON payloads.
* **Bearer tokens.** Send `Authorization: Bearer <access_token>` on every API request. Tokens come from ESW STS, never from an API host.
* **Tenant identifier.** Most endpoints include your `tenantCode`. The Package API identifies you with `brandCode`, and the Returns API uses an `identifier` in the path.
* **ISO codes.** Currencies use three-letter ISO 4217 codes and countries use two-letter ISO 3166 codes, in uppercase.
* **Check the number format for each API.** The Checkout and Order APIs send money amounts as strings such as `"89.95"`. The Customs Catalog, Package, and Returns APIs send amounts and weights as JSON numbers.
* **`metadataItems` need agreement.** Agree any key-value `metadataItems` with ESW before you send them.
* **Sandbox first.** Sandbox has its own STS and API base URLs. See [API Base URLs](broken://pages/7FvWQMF0kTK7HGhlQfmo#api-base-urls).

### Other APIs

For these APIs, start with their own overview and tutorials:

* [Package Management API v1](https://developer.esw.com/package-management/)
* [Callback API](https://developer.esw.com/callback-api/)

### More help

* [Test Cards](/getting-started/get-started-with-esw/quick-start-guide/test-cards.md) for sandbox payments
* [Best practices for APIs](/getting-started/get-started-with-esw/quick-start-guide/best-practices/apis.md) and [for webhooks](/getting-started/get-started-with-esw/quick-start-guide/best-practices/webhooks.md)
* [FAQs](/getting-started/get-started-with-esw/faqs.md) and the [Glossary](/getting-started/get-started-with-esw/glossary.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.esw.com/getting-started/get-started-with-esw/quick-start-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.