> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.bitbybit.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Shipping overview

> Manage shipping end-to-end via Open API — store locations, fee quoting, and the shipment lifecycle across GoSend, KiriminAja, and RideBlitz.

## What you can do

The Shipping API exposes one consistent surface for three Indonesian carriers and the merchant's saved pickup origins. With a single bitbybit API key you can:

* Manage **store locations** (pickup warehouses).
* **Discover** which carriers are connected and what services each one offers.
* **Look up** carrier-specific dictionaries (KiriminAja `kecamatan` / `kelurahan` IDs, RideBlitz allowed cities).
* **Quote shipping fees** with a unified request — the response shape is the same regardless of provider.
* **Create, update, cancel, and track shipments** linked to your existing orders.

## Carriers covered

<CardGroup cols={3}>
  <Card title="GoSend" icon="motorcycle">
    Gojek instant motorcycle / car delivery within select Indonesian cities. Best for same-day intra-city.
  </Card>

  <Card title="KiriminAja" icon="truck">
    Aggregator exposing JNE, J\&T, SiCepat, Anteraja, Lion Parcel, Ninja Xpress, TIKI, NCS, SAP, IDX, J\&T Cargo, and Sentral through the Express service. On-demand Instant delivery via KiriminAja's GoSend / Grab Express / Borzo integrations is **coming soon** — not yet available to Open API consumers.
  </Card>

  <Card title="RideBlitz" icon="bolt">
    Bali- and Java-focused electric-fleet instant courier with one-, two-, three-, and four-hour SLAs.
  </Card>
</CardGroup>

<Warning>
  **KiriminAja Instant is not yet available for Open API.** Calling `POST /shipping/calculate-fee` or `POST /shipping/shipments` with `provider: "kirimin_aja"` and `options.serviceType: "INSTANT"` (routing through KiriminAja's GoSend / Grab Express / Borzo integrations) is documented for forward compatibility only — the underlying integration is still rolling out and requests will not be fulfilled.

  For on-demand instant delivery today, call `provider: "gosend"` directly. KiriminAja **Express** (JNE, J\&T, SiCepat, Anteraja, and the other scheduled couriers listed above) is fully available.
</Warning>

## Typical end-to-end flow

<Steps>
  <Step title="Confirm provider is connected">
    Call `GET /shipping/providers` to see which carriers your merchant has linked. If `connected: false`, prompt the user to finish setup in **Settings > Integrations**.
  </Step>

  <Step title="Resolve addresses">
    For KiriminAja Express you need `kecamatanId` and `kelurahanId`. Use `GET /shipping/coverage/provinces` → `…/cities` → `…/districts` → `…/sub-districts`. For RideBlitz you need a `pickupCity` from `GET /shipping/coverage/cities?provider=ride_blitz`.
  </Step>

  <Step title="Quote the fee">
    Call `POST /shipping/calculate-fee` with `provider`, `origin`, `destination`, `package`, and any provider-specific `options`. The response always normalizes into `{ options: [{ serviceCode, serviceName, price, currency, … }] }`.
  </Step>

  <Step title="Create the shipment">
    Call `POST /shipping/shipments` with the chosen `provider`, `serviceName`, `fee`, full `sender` + `delivery` + `package`, and `orderId`. Leave `autoBook: false` (default) to just persist, or set `true` to immediately request pickup.
  </Step>

  <Step title="Book / cancel / track">
    Use `PATCH /shipping/shipments/{id}` with `triggerBooking: true` to request pickup later, `POST .../cancel` to cancel, and `GET .../tracking` to read the live carrier state.
  </Step>
</Steps>

## Authentication

All endpoints accept your bitbybit API key in the `x-api-key` header. Create one in **Settings > Developer**. The key must have the `BITCRM` product scope and an `orders` resource scope; the required action (`READ`, `WRITE`, or `DELETE`) depends on the endpoint.

<Note>
  Carrier credentials (GoSend `clientId`/`passKey`, KiriminAja `apiKey`, RideBlitz `customerCode`/`secretKey`) are stored per-company in **Settings > Integrations**. The Shipping API resolves them automatically — your code never sees them.
</Note>

## Webhook events

Mutations emit events to your registered webhook endpoints so you can react in real time without polling:

| Event                | Triggered by                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| `SHIPMENT_CREATED`   | `POST /shipping/shipments`                                                                       |
| `SHIPMENT_UPDATED`   | `PATCH /shipping/shipments/{id}`                                                                 |
| `SHIPMENT_BOOKED`    | `autoBook=true` on create, `triggerBooking=true` on update, or carrier webhook upgrading the row |
| `SHIPMENT_CANCELLED` | `POST /shipping/shipments/{id}/cancel`                                                           |

See the [Webhooks](/api-reference/webhooks/overview) section for delivery semantics and signature verification.

## Provider capability matrix

| Capability          | GoSend           | KiriminAja    | RideBlitz       |
| ------------------- | ---------------- | ------------- | --------------- |
| Quote fee           | ✓                | ✓             | ✓               |
| Coverage lookup     | —                | ✓             | ✓ (cities only) |
| Auto-book on create | —                | ✓             | ✓               |
| Cancel via API      | ✓ (if `orderNo`) | ✓ (after AWB) | ✓ (after AWB)   |
| Live tracking       | —                | ✓             | ✓               |

<Tip>
  GoSend booking is not exposed as an Open API action — pickup is handled through the Gojek merchant pickup flow inside the bitbybit app. Set `autoBook=true` for GoSend if you want to be future-compatible; the call succeeds and the shipment row is created with `shippingStatus: awaiting`, but no outbound carrier call is made.
</Tip>