---
updatedAt: 2026-10-16T10:55:30.000Z
agentTools:
  projectIndex: https://developers.easyship.com/llms.txt
---

# How to Track a Shipment

<HTMLBlock>{`
<style>
  /* Every rule is scoped to the guide wrapper class. The build doubles that class in each
     selector so it outranks ReadMe's .markdown-body rules; !important only where ReadMe wins anyway. */
  .es-guide.es-guide { --es-text: #374151; --es-muted: #6B7280; --es-head: #111827; --es-line: #E5E7EB; --es-soft: #F9FAFB; --es-link: #1d75b3; --es-link-soft: rgba(29,117,179,.08); --es-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
    font-family: inherit; color: var(--es-text); font-size: 15px; line-height: 1.65; max-width: 780px; margin: 0; padding: 0 0 40px; background: #FFFFFF; }
  .es-guide.es-guide *, .es-guide.es-guide *::before, .es-guide.es-guide *::after { box-sizing: border-box; }

  .es-guide.es-guide .subtitle { font-size: 16px; color: var(--es-muted); margin: 0 0 20px; line-height: 1.6; }
  .es-guide.es-guide h2 { font-size: 20px !important; font-weight: 600 !important; color: var(--es-head); margin: 0 0 12px !important; padding: 0 !important; border: 0 !important; letter-spacing: -0.01em; line-height: 1.3 !important; }
  .es-guide.es-guide h3 { font-size: 16px; font-weight: 600; color: var(--es-head); margin: 24px 0 8px; }
  .es-guide.es-guide section { padding: 0; margin: 0; }
  .es-guide.es-guide section + section { border-top: 1px solid var(--es-line); margin-top: 32px; padding-top: 28px; }
  .es-guide.es-guide p { margin: 0 0 12px; font-size: 15px; color: var(--es-text); }
  .es-guide.es-guide strong { color: var(--es-head); font-weight: 600; }
  .es-guide.es-guide ul { margin: 0 0 12px; padding-left: 20px; }
  .es-guide.es-guide ul li { font-size: 15px; line-height: 1.7; }

  /* Links: no underline anywhere (ReadMe forces one on .markdown-body a[href]) */
  .es-guide.es-guide a, .es-guide.es-guide a[href], .es-guide.es-guide a:hover, .es-guide.es-guide a:focus { color: var(--es-link); text-decoration: none !important; box-shadow: none !important; }
  .es-guide.es-guide a:hover { color: #165887; }

  /* Inline code (ReadMe wraps it in its own component; keep it quiet) */
  .es-guide.es-guide code, .es-guide.es-guide code span { font-family: var(--es-mono) !important; font-size: 13px !important; color: #1F2937 !important; background: #F3F4F6; padding: 1px 5px; border-radius: 4px; border: 0; white-space: normal; }
  .es-guide.es-guide code span { background: none; padding: 0; }

  /* Endpoint pills */
  .es-guide.es-guide .api-refs { display: flex; flex-wrap: wrap; gap: 8px; margin: 0 0 24px; padding: 0; }
  .es-guide.es-guide .api-ref-pill { display: inline-flex !important; align-items: center; gap: 8px; height: 30px; padding: 0 12px 0 6px; border-radius: 8px; border: 1px solid var(--es-line); background: #fff; font-family: var(--es-mono); font-size: 12.5px; line-height: 1; color: #1F2937 !important; white-space: nowrap; transition: border-color .15s, background .15s; }
  .es-guide.es-guide .api-ref-pill:hover { border-color: #C7D2DE; background: var(--es-soft); color: #111827 !important; }
  .es-guide.es-guide .method { display: inline-flex; align-items: center; height: 18px; padding: 0 6px; border-radius: 5px; font-family: var(--es-mono); font-size: 10.5px; font-weight: 700; letter-spacing: .02em; line-height: 1; background: rgba(29,117,179,.12); color: #165887; }
  .es-guide.es-guide .method.get { background: rgba(16,185,129,.14); color: #047857; }
  .es-guide.es-guide .method.delete { background: rgba(239,68,68,.12); color: #B91C1C; }
  .es-guide.es-guide .method.patch { background: rgba(245,158,11,.15); color: #B45309; }

  /* Callouts */
  .es-guide.es-guide .callout { background: var(--es-soft); border: 1px solid var(--es-line); border-left: 3px solid var(--es-link); padding: 12px 16px; border-radius: 8px; margin: 16px 0 !important; font-size: 14px; color: var(--es-text); }
  .es-guide.es-guide .callout.warn { border-left-color: #F59E0B; background: #FFFBEB; border-color: #FDE68A; }
  .es-guide.es-guide .callout.tip  { border-left-color: #10B981; background: #F0FDF4; border-color: #BBF7D0; }

  /* Code group (Mintlify / Razorpay style) */
  .es-guide.es-guide .es-codegroup { margin: 12px 0 20px; border: 1px solid rgba(3,7,18,.08); border-radius: 14px; background: var(--es-soft); padding: 2px; overflow: hidden; }
  .es-guide.es-guide .es-codehead { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 6px 12px 6px 14px; font-size: 12px; line-height: 20px; }
  .es-guide.es-guide .es-codetab { position: relative; font-weight: 600; color: var(--es-link); padding: 2px 0; }
  .es-guide.es-guide .es-codetab::after { content: ""; position: absolute; left: 0; right: 0; bottom: -7px; height: 2px; border-radius: 2px; background: var(--es-link); }
  .es-guide.es-guide .es-codemeta { font-family: var(--es-mono); font-size: 11.5px; color: var(--es-muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
  .es-guide.es-guide .es-status { display: inline-flex; align-items: center; gap: 6px; font-weight: 600; color: #047857; }
  .es-guide.es-guide .es-status::before { content: ""; width: 7px; height: 7px; border-radius: 50%; background: #10B981; }
  .es-guide.es-guide .es-code { display: block; white-space: pre; margin: 0; background: #FFFFFF; color: #24292F; border: 1px solid rgba(3,7,18,.06); border-radius: 12px; padding: 14px 16px; overflow-x: auto; font-family: var(--es-mono); font-size: 13px; line-height: 1.7; tab-size: 2; }
  .es-guide.es-guide .es-code .comment { color: #6E7781; font-style: italic; }
  .es-guide.es-guide .es-code .string  { color: #0A3069; }
  .es-guide.es-guide .es-code .key     { color: #0550AE; }
  .es-guide.es-guide .es-code .bool    { color: #CF222E; }
  .es-guide.es-guide .es-code .num     { color: #0550AE; }
  .es-guide.es-guide .es-code .method-line { color: #8250DF; font-weight: 600; }
  .es-guide.es-guide .es-code .flag    { color: #953800; }
  .es-guide.es-guide .es-code .cmd     { color: #8250DF; font-weight: 600; }

  /* Tables (ReadMe sets .markdown-body table { display:block }) */
  .es-guide.es-guide .table-wrap { overflow-x: auto; margin: 12px 0 20px; border: 1px solid var(--es-line); border-radius: 10px; }
  .es-guide.es-guide table { display: table !important; width: 100% !important; border-collapse: collapse !important; border: 0 !important; margin: 0 !important; font-size: 14px; table-layout: auto; }
  .es-guide.es-guide thead, .es-guide.es-guide tbody, .es-guide.es-guide tr { background: none !important; border: 0 !important; }
  .es-guide.es-guide th { text-align: left !important; font-weight: 600; font-size: 12px; text-transform: none; letter-spacing: 0; color: var(--es-muted); padding: 10px 14px !important; border: 0 !important; border-bottom: 1px solid var(--es-line) !important; background: var(--es-soft) !important; vertical-align: middle !important; }
  .es-guide.es-guide td { padding: 10px 14px !important; border: 0 !important; border-bottom: 1px solid var(--es-line) !important; vertical-align: top !important; font-size: 14px; color: var(--es-text); text-align: left !important; background: #fff !important; }
  .es-guide.es-guide tr:last-child td { border-bottom: 0 !important; }
  .es-guide.es-guide td p, .es-guide.es-guide th p { margin: 0 !important; }

  .es-guide.es-guide .badge { display: inline-block; font-size: 11.5px; font-weight: 600; padding: 1px 8px; border-radius: 999px; white-space: nowrap; line-height: 18px; }
  .es-guide.es-guide .badge-deprecated { background: #FEF3C7; color: #92400E; }
  .es-guide.es-guide .badge-latest     { background: #DCFCE7; color: #166534; }
  .es-guide.es-guide .badge-supported  { background: var(--es-link-soft); color: #165887; }
  .es-guide.es-guide .badge-error      { background: #FEE2E2; color: #991B1B; }
  .es-guide.es-guide .check { color: #059669; font-weight: 700; }
  .es-guide.es-guide .cross { color: #DC2626; font-weight: 700; }

  /* At a glance */
  .es-guide.es-guide .glance { display: flex; flex-wrap: wrap; border: 1px solid var(--es-line); border-radius: 10px; overflow: hidden; margin: 0 0 24px; }
  .es-guide.es-guide .glance > div { flex: 1 1 170px; padding: 12px 16px; border-right: 1px solid var(--es-line); margin-right: -1px; }
  .es-guide.es-guide .glance .g-label { font-size: 11.5px; font-weight: 600; color: var(--es-muted); margin-bottom: 2px; }
  .es-guide.es-guide .glance .g-value { font-size: 14px; font-weight: 500; color: var(--es-head); line-height: 1.45; }

  /* Cards */
  .es-guide.es-guide .card-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 12px; margin: 12px 0 20px; }
  .es-guide.es-guide .card { border: 1px solid var(--es-line); border-radius: 10px; padding: 16px 18px; background: #fff; }
  .es-guide.es-guide .card .card-icon { font-size: 18px; margin-bottom: 4px; }
  .es-guide.es-guide .card .card-head { font-size: 15px; font-weight: 600; color: var(--es-head); margin-bottom: 4px; }
  .es-guide.es-guide .card p { font-size: 14px; margin: 0 0 8px; }
  .es-guide.es-guide .card p:last-child { margin-bottom: 0; }
  .es-guide.es-guide .card .card-tag { display: inline-block; font-size: 11px; font-weight: 600; color: #165887; background: var(--es-link-soft); border-radius: 999px; padding: 1px 9px; margin-bottom: 8px; }

  /* Flow diagram */
  .es-guide.es-guide .flow { display: flex; flex-wrap: wrap; align-items: stretch; gap: 8px; margin: 8px 0 20px; }
  .es-guide.es-guide .flow .flow-step { flex: 1 1 150px; border: 1px solid var(--es-line); border-radius: 10px; padding: 10px 14px; background: var(--es-soft); }
  .es-guide.es-guide .flow .flow-num { font-size: 11.5px; font-weight: 600; color: var(--es-muted); }
  .es-guide.es-guide .flow .flow-title { font-size: 14px; font-weight: 600; color: var(--es-head); margin: 1px 0 2px; }
  .es-guide.es-guide .flow .flow-sub { font-size: 12px; color: var(--es-muted); font-family: var(--es-mono); word-break: break-word; }
  .es-guide.es-guide .flow .flow-arrow { align-self: center; color: #9CA3AF; font-size: 16px; flex: 0 0 auto; }

  .es-guide.es-guide .example-block { border: 1px solid var(--es-line); border-radius: 10px; padding: 16px 20px; margin-bottom: 20px; background: var(--es-soft); }

  /* Numbered steps (ReadMe adds list padding and li+li margins) */
  .es-guide.es-guide .step-list { counter-reset: steps; list-style: none !important; padding: 0 !important; margin: 0 0 16px !important; }
  .es-guide.es-guide .step-list > li { counter-increment: steps; display: flex; gap: 14px; margin: 0 0 24px !important; padding: 0 !important; list-style: none !important; }
  .es-guide.es-guide .step-list > li::before { content: counter(steps); flex-shrink: 0; width: 24px; height: 24px; background: var(--es-link-soft); color: #165887; border-radius: 50%; font-size: 12px; font-weight: 700; display: flex; align-items: center; justify-content: center; margin-top: 1px; }
  .es-guide.es-guide .step-body { flex: 1; min-width: 0; }
  .es-guide.es-guide .step-body > strong { display: block; font-size: 15px; color: var(--es-head); margin-bottom: 6px; }
  .es-guide.es-guide .step-body p { margin: 0 0 10px; }

  .es-guide.es-guide .faq-item { border-bottom: 1px solid var(--es-line); padding: 14px 0; }
  .es-guide.es-guide .faq-item:last-child { border-bottom: 0; }
  .es-guide.es-guide .faq-q { font-weight: 600; font-size: 15px; color: var(--es-head); margin-bottom: 4px; }
  .es-guide.es-guide .faq-a { font-size: 14.5px; color: var(--es-text); }

  .es-guide.es-guide .related-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(220px, 1fr)); gap: 10px; margin-top: 8px; }
  .es-guide.es-guide .related-card { display: flex !important; flex-direction: column; gap: 2px; padding: 12px 14px; border: 1px solid var(--es-line); border-radius: 10px; background: #fff; transition: border-color .15s; }
  .es-guide.es-guide .related-card:hover { border-color: #C7D2DE; }
  .es-guide.es-guide .related-card .card-title { font-size: 14px; font-weight: 600; color: var(--es-head); }
  .es-guide.es-guide .related-card .card-sub { font-size: 12px; color: var(--es-muted); font-family: var(--es-mono); }

  .es-guide.es-guide .notice { border: 1px solid #FDE68A; border-left: 3px solid #F59E0B; background: #FFFBEB; border-radius: 8px; padding: 12px 16px; margin: 0 0 24px; }
  .es-guide.es-guide .notice-header { display: flex; align-items: center; flex-wrap: wrap; gap: 8px; margin-bottom: 4px; }
  .es-guide.es-guide .notice-title { font-size: 14.5px; font-weight: 600; color: var(--es-head); }
  .es-guide.es-guide .notice-date { font-size: 11.5px; font-weight: 600; color: #92400E; background: #FEF3C7; padding: 1px 8px; border-radius: 999px; white-space: nowrap; }
  .es-guide.es-guide .notice p { margin: 0 0 4px; font-size: 14px; }
  .es-guide.es-guide .notice p:last-child { margin-bottom: 0; }

  .es-guide.es-guide .toc { background: var(--es-soft); border: 1px solid var(--es-line); border-radius: 10px; padding: 14px 18px; margin: 0 0 28px; }
  .es-guide.es-guide .toc-title { font-size: 12px; font-weight: 600; color: var(--es-muted); margin-bottom: 6px; }
  .es-guide.es-guide .toc ol { margin: 0 !important; padding-left: 18px !important; }
  .es-guide.es-guide .toc li { font-size: 14px; line-height: 1.8; margin: 0 !important; }

  /* Remove before publishing: marks facts that product still needs to confirm */
  .es-guide.es-guide .confirm { background: #FEF08A; color: #713F12; font-size: 11px; font-weight: 700; padding: 1px 6px; border-radius: 4px; white-space: nowrap; }

  .es-guide.es-guide .doc-footer { margin-top: 40px; padding-top: 16px; border-top: 1px solid var(--es-line); font-size: 13px; color: var(--es-muted); }

  @media (max-width: 640px) {
    .es-guide.es-guide .flow .flow-arrow { display: none; }
    .es-guide.es-guide .flow .flow-step { flex-basis: 100%; }
    .es-guide.es-guide .es-code { font-size: 12px; padding: 12px; }
    .es-guide.es-guide .glance > div { flex-basis: 100%; border-right: 0; border-bottom: 1px solid var(--es-line); }
  }
</style>

<div class="es-guide">
<p class="subtitle">Follow every parcel from label to doorstep. Easyship turns each courier's events into one set of statuses, which you can pull through the API or receive by webhook.</p>

<div class="api-refs">
  <a class="api-ref-pill" href="https://developers.easyship.com/reference/shipments_trackings_index"><span class="method get">GET</span>/shipments/trackings</a>
  <a class="api-ref-pill" href="https://developers.easyship.com/reference/trackings_list_supported_couriers"><span class="method get">GET</span>/trackings/supported_couriers</a>
  <a class="api-ref-pill" href="https://developers.easyship.com/reference/trackings_create"><span class="method">POST</span>/trackings</a>
  <a class="api-ref-pill" href="https://developers.easyship.com/reference/trackings_index"><span class="method get">GET</span>/trackings</a>
  <a class="api-ref-pill" href="https://developers.easyship.com/reference/trackings_show"><span class="method get">GET</span>/trackings/{id}</a>
  <a class="api-ref-pill" href="https://developers.easyship.com/reference/trackings_delete"><span class="method delete">DELETE</span>/trackings/{id}</a>
</div>

<div class="glance">
  <div><div class="g-label">What it does</div><div class="g-value">Gives you status and checkpoint updates for parcels</div></div>
  <div><div class="g-label">Works with</div><div class="g-value">Easyship labels and labels from other providers</div></div>
  <div><div class="g-label">Delivery</div><div class="g-value">Webhooks (recommended) or polling</div></div>
  <div><div class="g-label">Scopes</div><div class="g-value"><code>track</code> &#183; <code>track_3p</code> (advanced)</div></div>
</div>

<div class="toc">
  <div class="toc-title">On this page</div>
  <ol>
    <li><a href="#choose">Which tracking do I need?</a></li>
    <li><a href="#easyship">Track Easyship shipments</a></li>
    <li><a href="#external">Track shipments from other providers</a></li>
    <li><a href="#webhooks">Get updates by webhook</a></li>
    <li><a href="#faq">FAQ and testing</a></li>
  </ol>
</div>

<section id="choose">
  <h2>Which tracking do I need?</h2>
  <div class="card-grid">
    <div class="card pick">
      <span class="card-tag">EASYSHIP LABEL</span>
      <div class="card-head">I bought the label through Easyship</div>
      <p>Nothing to set up. The shipment is tracked automatically.</p>
      <p>Scope: <code>public.track:read</code></p>
      <p><a href="#easyship">Go to Easyship labels &#8594;</a></p>
    </div>
    <div class="card pick">
      <span class="card-tag">OTHER LABEL</span>
      <div class="card-head">My label comes from another provider</div>
      <p>Register the tracking number once. Easyship then tracks it for you.</p>
      <p>Scope: <code>public.track_3p:read</code> / <code>:write</code> (advanced; ask your account manager)</p>
      <p><a href="#external">Go to other providers &#8594;</a></p>
    </div>
  </div>
  <div class="callout"><strong>Base URL:</strong> <code>https://public-api.easyship.com/2024-09</code></div>
</section>

<section id="easyship">
  <h2>Track Easyship shipments</h2>
<div class="es-codegroup"><div class="es-codehead"><span class="es-codetab">cURL</span><span class="es-codemeta">GET /2024-09/shipments/trackings</span></div><div class="es-code"><span class="cmd">curl</span> <span class="string">"https://public-api.easyship.com/2024-09/shipments/trackings?easyship_shipment_id=ESUS100000001&amp;include_checkpoints=true"</span> \
  <span class="flag">-H</span> <span class="string">"Authorization: Bearer $EASYSHIP_TOKEN"</span></div></div>
  <div class="table-wrap"><table>
    <thead><tr><th>Query parameter</th><th>Use it to</th></tr></thead>
    <tbody>
      <tr><td><code>easyship_shipment_id</code></td><td>Get one shipment</td></tr>
      <tr><td><code>platform_order_number</code></td><td>Look up by your order number</td></tr>
      <tr><td><code>include_checkpoints=true</code></td><td>Include the full event history</td></tr>
    </tbody>
  </table></div>
</section>

<section id="external">
  <h2>Track shipments from other providers</h2>
  <div class="flow">
    <div class="flow-step"><div class="flow-num">Step 1</div><div class="flow-title">Check the courier</div><div class="flow-sub">GET /trackings/supported_couriers</div></div>
    <div class="flow-arrow">&#8594;</div>
    <div class="flow-step"><div class="flow-num">Step 2</div><div class="flow-title">Register tracking</div><div class="flow-sub">POST /trackings</div></div>
    <div class="flow-arrow">&#8594;</div>
    <div class="flow-step"><div class="flow-num">Step 3</div><div class="flow-title">Get updates</div><div class="flow-sub">webhook or GET /trackings/{id}</div></div>
  </div>
  <ol class="step-list">
    <li><div class="step-body">
      <strong>Check that the courier is supported</strong>
      <p>You can filter by <code>umbrella_name</code> (e.g. <code>DHL</code>) and <code>origin_country_alpha2</code>.</p>
<div class="es-codegroup"><div class="es-codehead"><span class="es-codetab">cURL</span><span class="es-codemeta">GET /2024-09/trackings/supported_couriers</span></div><div class="es-code"><span class="cmd">curl</span> <span class="string">"https://public-api.easyship.com/2024-09/trackings/supported_couriers?umbrella_name=DHL&amp;origin_country_alpha2=US"</span> \
  <span class="flag">-H</span> <span class="string">"Authorization: Bearer $EASYSHIP_TOKEN"</span></div></div>
<div class="es-codegroup"><div class="es-codehead"><span class="es-codetab">Response</span><span class="es-codemeta"><span class="es-status">200 OK</span></span></div><div class="es-code">{
  <span class="key">"courier_services"</span>: [
    {
      <span class="key">"id"</span>: <span class="string">"137a79e8-ae1c-4369-9855-44cf8ff784c4"</span>,
      <span class="key">"name"</span>: <span class="string">"DHL Express"</span>,
      <span class="key">"umbrella_name"</span>: <span class="string">"DHL"</span>,
      <span class="key">"origin_country_alpha2"</span>: <span class="string">"US"</span>
    }
  ]
}</div></div>
      <p>Pass the <code>id</code> you get back as <code>courier_service_id</code> in the next step.</p>
      <div class="callout"><strong>Courier not in that list?</strong> If Easyship doesn't generate labels for the courier, send <code>courier_service_name</code> instead of <code>courier_service_id</code>. Get the exact name from <a href="https://developers.easyship.com/reference/trackings_external_courier_services_index"><code>GET /trackings/external_courier_services</code></a>.</div>
    </div></li>
    <li><div class="step-body">
      <strong>Register the tracking number</strong>
<div class="es-codegroup"><div class="es-codehead"><span class="es-codetab">cURL</span><span class="es-codemeta">POST /2024-09/trackings</span></div><div class="es-code"><span class="cmd">curl</span> <span class="flag">-X</span> <span class="method-line">POST</span> https://public-api.easyship.com/2024-09/trackings \
  <span class="flag">-H</span> <span class="string">"Authorization: Bearer $EASYSHIP_TOKEN"</span> \
  <span class="flag">-H</span> <span class="string">"Content-Type: application/json"</span> \
  <span class="flag">-d</span> '{
    <span class="key">"tracking_number"</span>: <span class="string">"0114827"</span>,
    <span class="key">"courier_service_id"</span>: <span class="string">"137a79e8-ae1c-4369-9855-44cf8ff784c4"</span>,
    <span class="key">"platform_order_number"</span>: <span class="string">"ORDER-1001"</span>,
    <span class="key">"origin_address_id"</span>: <span class="string">"01563646-58c1-4607-8fe0-cae3e33c0001"</span>,
    <span class="key">"destination_address"</span>: {
      <span class="key">"line_1"</span>: <span class="string">"123 Test Street"</span>, <span class="key">"city"</span>: <span class="string">"Singapore"</span>, <span class="key">"state"</span>: <span class="string">"Singapore"</span>,
      <span class="key">"postal_code"</span>: <span class="string">"247964"</span>, <span class="key">"country_alpha2"</span>: <span class="string">"SG"</span>,
      <span class="key">"contact_name"</span>: <span class="string">"Foo Bar"</span>, <span class="key">"contact_phone"</span>: <span class="string">"+65 6910 1185"</span>, <span class="key">"contact_email"</span>: <span class="string">"customer@example.com"</span>
    },
    <span class="key">"items"</span>: [{ <span class="key">"description"</span>: <span class="string">"iPhone"</span>, <span class="key">"quantity"</span>: <span class="num">1</span> }]
  }'</div></div>
      <div class="table-wrap"><table>
        <thead><tr><th>Field</th><th>Notes</th></tr></thead>
        <tbody>
          <tr><td><code>tracking_number</code></td><td>Required. The courier's tracking number</td></tr>
          <tr><td><code>courier_service_id</code> or <code>courier_service_name</code></td><td>One is required: the ID from step 1, or the name from <code>/trackings/external_courier_services</code></td></tr>
          <tr><td><code>platform_order_number</code></td><td>Your order number. It makes it easy to match webhooks to orders</td></tr>
          <tr><td><code>origin_address_id</code> or <code>origin_address</code></td><td>A saved address ID, or the full address</td></tr>
          <tr><td><code>destination_address</code></td><td>The full delivery address</td></tr>
          <tr><td><code>items</code></td><td><code>description</code> and <code>quantity</code></td></tr>
        </tbody>
      </table></div>
    </div></li>
    <li><div class="step-body">
      <strong>Check status</strong>
<div class="es-codegroup"><div class="es-codehead"><span class="es-codetab">cURL</span><span class="es-codemeta">GET /2024-09/trackings</span></div><div class="es-code"><span class="comment"># One tracking</span>
<span class="cmd">curl</span> https://public-api.easyship.com/2024-09/trackings/{tracking_id} \
  <span class="flag">-H</span> <span class="string">"Authorization: Bearer $EASYSHIP_TOKEN"</span>

<span class="comment"># Many, filtered (origin_country_alpha2, destination_country_alpha2, source=easyship|external, tracking_state)</span>
<span class="cmd">curl</span> <span class="string">"https://public-api.easyship.com/2024-09/trackings?tracking_state=active"</span> \
  <span class="flag">-H</span> <span class="string">"Authorization: Bearer $EASYSHIP_TOKEN"</span></div></div>
      <p>Each tracking in the response has two status fields:</p>
      <ul>
        <li><code>status</code>: the latest courier status in plain words, e.g. <em>In Transit</em> or <em>Delivered</em>. Show this to your users.</li>
        <li><code>tracking_state</code>: the state of Easyship's tracking for this number. Use it to filter, e.g. <code>?tracking_state=active</code>.</li>
      </ul>
      <p>Each tracking also includes <code>eta_date</code> and a <code>tracking_page_url</code>.</p>
      <div class="table-wrap"><table>
        <thead><tr><th><code>tracking_state</code></th><th>Meaning</th></tr></thead>
        <tbody>
          <tr><td><span class="badge badge-supported">active</span></td><td>Easyship is tracking the number and recording courier updates. Trackings created with <code>POST /trackings</code> start here.</td></tr>
          <tr><td><span class="badge badge-latest">completed</span></td><td>The courier reported a final event (e.g. delivered). No more updates.</td></tr>
          <tr><td><span class="badge badge-deprecated">pending</span></td><td>Multi-leg shipments only: a later leg that is waiting for the previous leg to complete. It becomes <code>active</code> automatically.</td></tr>
          <tr><td><span class="badge badge-deprecated">created</span></td><td>Registered but tracking hasn't started yet. Rarely seen through the API.</td></tr>
          <tr><td><span class="badge badge-error">overwritten_by_admin</span></td><td>Replaced or switched off by Easyship, e.g. after a tracking number correction. No longer updated.</td></tr>
        </tbody>
      </table></div>
    </div></li>
  </ol>
</section>

<section id="webhooks">
  <h2>Get updates by webhook</h2>
  <p>Every poll counts against your API rate limits. In production, subscribe to these events with the <a href="https://developers.easyship.com/docs/webhooks-guide">Webhooks API</a> instead:</p>
  <div class="table-wrap"><table>
    <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
    <tbody>
      <tr><td><code>shipment_tracking_status_changed</code></td><td>The overall status changes, e.g. in transit &#8594; delivered</td></tr>
      <tr><td><code>shipment_tracking_checkpoints_created</code></td><td>The courier reports a new event</td></tr>
    </tbody>
  </table></div>
  <div class="callout tip"><strong>Why webhooks?</strong> You hear about changes sooner, make fewer API calls, and stay well clear of rate limits.</div>
</section>

<section id="faq">
  <h2>FAQ and testing</h2>
  <div class="faq-item">
    <div class="faq-q">Why hasn't <code>status</code> changed when my tracking is <code>active</code>?</div>
    <div class="faq-a">Couriers can take a few hours to show the first event for a new tracking number. If nothing appears, check the tracking number and the courier you sent.</div>
  </div>
  <div class="faq-item">
    <div class="faq-q">Why does <code>POST /trackings</code> return an error about the courier?</div>
    <div class="faq-a">Send either a <code>courier_service_id</code> from step 1 or an exact <code>courier_service_name</code> from <code>/trackings/external_courier_services</code>.</div>
  </div>
  <div class="faq-item">
    <div class="faq-q">How do I test status changes in sandbox?</div>
    <div class="faq-a">Use <a href="https://developers.easyship.com/reference/sandbox_trackings_update">Update a tracking (sandbox only)</a> to simulate a status change. It isn't available in production.</div>
  </div>
</section>

<section id="related">
  <h2>Related</h2>
  <div class="related-grid">
    <a class="related-card" href="https://developers.easyship.com/docs/webhooks-guide"><span class="card-title">Webhooks Guide</span><span class="card-sub">Guide</span></a>
    <a class="related-card" href="https://developers.easyship.com/docs/how-to-insure-a-shipment"><span class="card-title">How to Insure a Shipment</span><span class="card-sub">Guide</span></a>
    <a class="related-card" href="https://developers.easyship.com/docs/overview-flow-guide"><span class="card-title">Overview Flow Guide</span><span class="card-sub">Guide</span></a>
  </div>
</section>

<div class="doc-footer">

  API version: <strong>2024-09</strong> &#183; Questions? Contact your account manager or <a href="mailto:support@easyship.com">support@easyship.com</a>
</div>
</div>

`}</HTMLBlock>