curl --request POST \
  --url https://api.bitbybit.studio/customer/api/open/v1/shipping/shipments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "orderId": "ord_2X9q…",
  "provider": "kirimin_aja",
  "name": "JNE REG",
  "fee": 22000,
  "currency": "IDR",
  "serviceType": "EXPRESS",
  "serviceName": "JNE Regular",
  "selectedExpedition": "jne:reg",
  "courierGroup": "regular",
  "storeLocationId": "loc_8…",
  "sender": {
    "name": "Main Warehouse",
    "phone": "+6281234567890",
    "address": "Jl. KH. Moh. Mansyur No. 12",
    "coordinates": {
      "lat": -6.1539,
      "lng": 106.8054
    },
    "city": "Kota Jakarta Barat",
    "province": "DKI Jakarta",
    "country": "Indonesia",
    "zip": "11210",
    "kecamatan": "Tambora",
    "kecamatanId": 2412,
    "kelurahan": "Tanah Sereal",
    "kelurahanId": 33417
  },
  "delivery": {
    "name": "Andi Wijaya",
    "phone": "+6285671234567",
    "address": "Jl. Asia Afrika No. 8",
    "coordinates": {
      "lat": -6.9175,
      "lng": 107.6191
    },
    "city": "Kota Bandung",
    "province": "Jawa Barat",
    "country": "Indonesia",
    "zip": "40111",
    "kecamatan": "Sumur Bandung",
    "kecamatanId": 1981,
    "kelurahan": "Braga",
    "kelurahanId": 27543
  },
  "package": {
    "weight": 1500,
    "length": 30,
    "width": 20,
    "height": 10,
    "itemName": "Kemeja batik",
    "itemType": "fashion",
    "itemValue": 250000,
    "itemQty": 1
  },
  "insurance": false,
  "packageHandover": "DROPOFF",
  "autoBook": false
}
'

{
  "data": {
    "id": "<string>",
    "orderId": "<string>",
    "provider": "gosend",
    "providerLabel": "<string>",
    "name": "<string>",
    "fee": 123,
    "currency": "<string>",
    "shippingStatus": "confirmed",
    "serviceType": "INSTANT",
    "serviceName": "<string>",
    "selectedExpedition": "<string>",
    "selectedDelivery": "<string>",
    "courierGroup": "<string>",
    "vehicleType": "TWO_WHEEL",
    "bikeFuelType": "<string>",
    "packageHandover": "PICKUP",
    "pickupSchedule": "2023-11-07T05:31:56Z",
    "storeLocationId": "<string>",
    "sender": {
      "name": "<string>",
      "phone": "<string>",
      "email": "<string>",
      "address": "<string>",
      "notes": "<string>",
      "city": "<string>",
      "province": "<string>",
      "country": "<string>",
      "zip": "<string>",
      "kecamatan": "<string>",
      "kecamatanId": 123,
      "kelurahan": "<string>",
      "kelurahanId": 123,
      "coordinates": {
        "lat": 0,
        "lng": 0
      }
    },
    "delivery": {
      "name": "<string>",
      "phone": "<string>",
      "email": "<string>",
      "address": "<string>",
      "notes": "<string>",
      "city": "<string>",
      "province": "<string>",
      "country": "<string>",
      "zip": "<string>",
      "kecamatan": "<string>",
      "kecamatanId": 123,
      "kelurahan": "<string>",
      "kelurahanId": 123,
      "coordinates": {
        "lat": 0,
        "lng": 0
      }
    },
    "package": {
      "weight": 123,
      "length": 123,
      "width": 123,
      "height": 123,
      "itemName": "<string>",
      "itemType": "<string>",
      "itemValue": 123,
      "itemQty": 123,
      "notes": "<string>"
    },
    "driver": {
      "name": "<string>",
      "phone": "<string>",
      "photo": "<string>",
      "licensePlate": "<string>"
    },
    "insurance": true,
    "insuranceFee": 123,
    "insuranceAmount": 123,
    "discountAmount": 123,
    "discountPercentage": 123,
    "distance": 123,
    "trackingUrl": "<string>",
    "awb": "<string>",
    "orderNo": "<string>",
    "bookingId": "<string>",
    "pickupNumber": "<string>",
    "paymentId": "<string>",
    "paymentStatus": "<string>",
    "statusCode": 123,
    "cancellationReason": "<string>",
    "cancelledBy": "<string>",
    "cancelledSource": "<string>",
    "eventTimestamp": "<string>"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "origin.districtId is required for KiriminAja Express"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Shipments

Create shipment

Persist a new shipment attached to an existing Order. The shipment is created with shippingStatus: awaiting and is NOT booked with the carrier unless you set autoBook: true.

When to set autoBook: true — only when you already have all sender/delivery/package details and want to immediately request pickup with KiriminAja or RideBlitz. For GoSend the auto-book flag is accepted but no outbound call is made (GoSend booking happens via the Gojek pickup flow in the merchant app).

If the carrier booking fails, the shipment row is still persisted; the response returns a 400 with both data (the persisted row) and error (the booking failure reason) so you can decide whether to retry via POST /shipping/shipments/{id}/cancel followed by a fresh create.

POST

shipping

shipments

curl --request POST \
  --url https://api.bitbybit.studio/customer/api/open/v1/shipping/shipments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "orderId": "ord_2X9q…",
  "provider": "kirimin_aja",
  "name": "JNE REG",
  "fee": 22000,
  "currency": "IDR",
  "serviceType": "EXPRESS",
  "serviceName": "JNE Regular",
  "selectedExpedition": "jne:reg",
  "courierGroup": "regular",
  "storeLocationId": "loc_8…",
  "sender": {
    "name": "Main Warehouse",
    "phone": "+6281234567890",
    "address": "Jl. KH. Moh. Mansyur No. 12",
    "coordinates": {
      "lat": -6.1539,
      "lng": 106.8054
    },
    "city": "Kota Jakarta Barat",
    "province": "DKI Jakarta",
    "country": "Indonesia",
    "zip": "11210",
    "kecamatan": "Tambora",
    "kecamatanId": 2412,
    "kelurahan": "Tanah Sereal",
    "kelurahanId": 33417
  },
  "delivery": {
    "name": "Andi Wijaya",
    "phone": "+6285671234567",
    "address": "Jl. Asia Afrika No. 8",
    "coordinates": {
      "lat": -6.9175,
      "lng": 107.6191
    },
    "city": "Kota Bandung",
    "province": "Jawa Barat",
    "country": "Indonesia",
    "zip": "40111",
    "kecamatan": "Sumur Bandung",
    "kecamatanId": 1981,
    "kelurahan": "Braga",
    "kelurahanId": 27543
  },
  "package": {
    "weight": 1500,
    "length": 30,
    "width": 20,
    "height": 10,
    "itemName": "Kemeja batik",
    "itemType": "fashion",
    "itemValue": 250000,
    "itemQty": 1
  },
  "insurance": false,
  "packageHandover": "DROPOFF",
  "autoBook": false
}
'

{
  "data": {
    "id": "<string>",
    "orderId": "<string>",
    "provider": "gosend",
    "providerLabel": "<string>",
    "name": "<string>",
    "fee": 123,
    "currency": "<string>",
    "shippingStatus": "confirmed",
    "serviceType": "INSTANT",
    "serviceName": "<string>",
    "selectedExpedition": "<string>",
    "selectedDelivery": "<string>",
    "courierGroup": "<string>",
    "vehicleType": "TWO_WHEEL",
    "bikeFuelType": "<string>",
    "packageHandover": "PICKUP",
    "pickupSchedule": "2023-11-07T05:31:56Z",
    "storeLocationId": "<string>",
    "sender": {
      "name": "<string>",
      "phone": "<string>",
      "email": "<string>",
      "address": "<string>",
      "notes": "<string>",
      "city": "<string>",
      "province": "<string>",
      "country": "<string>",
      "zip": "<string>",
      "kecamatan": "<string>",
      "kecamatanId": 123,
      "kelurahan": "<string>",
      "kelurahanId": 123,
      "coordinates": {
        "lat": 0,
        "lng": 0
      }
    },
    "delivery": {
      "name": "<string>",
      "phone": "<string>",
      "email": "<string>",
      "address": "<string>",
      "notes": "<string>",
      "city": "<string>",
      "province": "<string>",
      "country": "<string>",
      "zip": "<string>",
      "kecamatan": "<string>",
      "kecamatanId": 123,
      "kelurahan": "<string>",
      "kelurahanId": 123,
      "coordinates": {
        "lat": 0,
        "lng": 0
      }
    },
    "package": {
      "weight": 123,
      "length": 123,
      "width": 123,
      "height": 123,
      "itemName": "<string>",
      "itemType": "<string>",
      "itemValue": 123,
      "itemQty": 123,
      "notes": "<string>"
    },
    "driver": {
      "name": "<string>",
      "phone": "<string>",
      "photo": "<string>",
      "licensePlate": "<string>"
    },
    "insurance": true,
    "insuranceFee": 123,
    "insuranceAmount": 123,
    "discountAmount": 123,
    "discountPercentage": 123,
    "distance": 123,
    "trackingUrl": "<string>",
    "awb": "<string>",
    "orderNo": "<string>",
    "bookingId": "<string>",
    "pickupNumber": "<string>",
    "paymentId": "<string>",
    "paymentStatus": "<string>",
    "statusCode": 123,
    "cancellationReason": "<string>",
    "cancelledBy": "<string>",
    "cancelledSource": "<string>",
    "eventTimestamp": "<string>"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "origin.districtId is required for KiriminAja Express"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Authorizations

x-api-key

string

header

required

API key for authentication. Create one in Settings > Developer. The key must have the BITCRM product scope and an orders resource scope; required action depends on the endpoint (READ, WRITE, or DELETE).

Body

application/json

orderId

string

required

ID of an Order in this company. Required — every shipment is attached to an order.

provider

enum<string>

required

Provider/courier code. gosend, kirimin_aja, and ride_blitz are externally integrated; jne is a passthrough placeholder; custom is for merchant-defined methods.

Available options:

gosend,

kirimin_aja,

ride_blitz,

jne,

custom

name

string

required

Human-readable label, e.g. JNE REG or GoSend Instant.

Maximum string length: 255

fee

number<double>

required

Shipping cost in the smallest unit of currency (e.g. 22000 = IDR 22,000).

Required range: x >= 0

sender

object

required

Show child attributes

delivery

object

required

Show child attributes

package

object

required

Show child attributes

currency

string

default:IDR

serviceType

enum<string>

Service category. INSTANT = on-demand intra-city; EXPRESS = scheduled inter-city.

Available options:

INSTANT,

EXPRESS

serviceName

string

selectedExpedition

string

Provider service identifier, e.g. jne:reg, instant_2_hours, Instant.

selectedDelivery

string

courierGroup

string

KiriminAja Express group: regular, economy, one_day, cargo, next_day.

vehicleType

enum<string>

Vehicle requested for the pickup. TWO_WHEEL = motorcycle, FOUR_WHEEL = car.

Available options:

TWO_WHEEL,

FOUR_WHEEL

bikeFuelType

enum<string>

RideBlitz fuel preference. green = electric fleet (lower emissions, may have limited availability).

Available options:

regular,

green

packageHandover

enum<string>

How the merchant hands the package to the carrier. PICKUP = courier picks up from the store, DROPOFF = merchant drops off at carrier hub.

Available options:

PICKUP,

DROPOFF

pickupSchedule

string<date-time>

ISO-8601 timestamp (with offset) when KiriminAja Express should pick up. Required when packageHandover=PICKUP for KA.

storeLocationId

string

Optional — link this shipment to a saved store location for analytics + future booking lookups.

insurance

boolean

insuranceFee

number<double>

Required range: x >= 0

insuranceAmount

number<double>

Required range: x >= 0

discountAmount

number<double>

Required range: x >= 0

discountPercentage

number<double>

Required range: 0 <= x <= 100

distance

number<double>

Pickup → delivery distance in km.

Required range: x >= 0

autoBook

boolean

default:false

When true, immediately request pickup with the carrier after persisting. Supported for kirimin_aja and ride_blitz.

Response

Shipment created.

data

object

Show child attributes

Getting Started

Customers

Loyalty (bitLogin)

Loyalty (Customer)

Orders

Shipping

Products

Messaging

Analytics

Webhooks

Create shipment

Authorizations

Body

Response