> ## 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. # 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. ## OpenAPI ````yaml POST /shipping/shipments openapi: 3.1.0 info: title: bitbybit Open API — Shipping description: >- Programmatic access to bitbybit shipping: store locations, provider discovery, coverage lookup, fee quoting, and the full shipment lifecycle (create, book, update, cancel, track) across GoSend, KiriminAja, and RideBlitz. version: 1.0.0 contact: name: bitbybit Support url: https://bitbybit.studio servers: - url: https://api.bitbybit.studio/customer/api/open/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Store Locations description: >- Manage warehouse / pickup origin addresses. Couriers pick up from these locations when a shipment is booked. - name: Providers description: Discover connected carriers and the services each carrier offers. - name: Coverage description: >- Look up the courier-specific province / city / district / sub-district dictionaries needed to populate addresses and quote fees. - name: Fee Calculation description: Quote shipping fees across carriers using one unified request shape. - name: Shipments description: >- Create, update, cancel, and track shipments. A shipment is always attached to an Order. paths: /shipping/shipments: post: tags: - Shipments summary: Create shipment description: >- 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. operationId: createShipment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateShipmentInput' examples: kiriminAjaExpress: summary: KiriminAja Express — persist only (autoBook=false) value: 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 rideBlitzAutoBook: summary: >- RideBlitz — create and immediately request pickup (autoBook=true) value: orderId: ord_3Y… provider: ride_blitz name: RideBlitz Instant 2h fee: 35000 currency: IDR serviceType: INSTANT serviceName: Instant 2 Hours selectedExpedition: instant_2_hours vehicleType: TWO_WHEEL bikeFuelType: green sender: name: Warung Bali phone: '+6281200000000' address: Jl. Sunset Road 88 coordinates: lat: -8.7202 lng: 115.1727 city: Kota Denpasar province: Bali delivery: name: Maya Putri phone: '+6285711112222' address: Jl. Hayam Wuruk 12 coordinates: lat: -8.6478 lng: 115.2186 city: Kota Denpasar province: Bali package: weight: 1200 itemName: Nasi campur (2 box) itemValue: 80000 itemQty: 2 autoBook: true responses: '201': description: Shipment created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Shipment' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' components: schemas: CreateShipmentInput: type: object required: - orderId - provider - name - fee - sender - delivery - package properties: orderId: type: string description: >- ID of an Order in this company. Required — every shipment is attached to an order. provider: $ref: '#/components/schemas/ShippingProvider' name: type: string maxLength: 255 description: Human-readable label, e.g. `JNE REG` or `GoSend Instant`. fee: type: number format: double minimum: 0 description: >- Shipping cost in the smallest unit of `currency` (e.g. `22000` = IDR 22,000). currency: type: string default: IDR serviceType: $ref: '#/components/schemas/ServiceType' serviceName: type: string selectedExpedition: type: string description: >- Provider service identifier, e.g. `jne:reg`, `instant_2_hours`, `Instant`. selectedDelivery: type: string courierGroup: type: string description: >- KiriminAja Express group: `regular`, `economy`, `one_day`, `cargo`, `next_day`. vehicleType: $ref: '#/components/schemas/VehicleType' bikeFuelType: $ref: '#/components/schemas/BikeFuelType' packageHandover: $ref: '#/components/schemas/PackageHandover' pickupSchedule: type: string format: date-time description: >- ISO-8601 timestamp (with offset) when KiriminAja Express should pick up. Required when `packageHandover=PICKUP` for KA. storeLocationId: type: string description: >- Optional — link this shipment to a saved store location for analytics + future booking lookups. sender: $ref: '#/components/schemas/AddressInput' delivery: $ref: '#/components/schemas/AddressInput' package: $ref: '#/components/schemas/PackageInput' insurance: type: boolean insuranceFee: type: number format: double minimum: 0 insuranceAmount: type: number format: double minimum: 0 discountAmount: type: number format: double minimum: 0 discountPercentage: type: number format: double minimum: 0 maximum: 100 distance: type: number format: double minimum: 0 description: Pickup → delivery distance in km. autoBook: type: boolean default: false description: >- When `true`, immediately request pickup with the carrier after persisting. Supported for `kirimin_aja` and `ride_blitz`. Shipment: type: object properties: id: type: string orderId: type: string nullable: true provider: $ref: '#/components/schemas/ShippingProvider' providerLabel: type: string description: Human-readable provider name (e.g. `KiriminAja`). name: type: string nullable: true fee: type: number format: double nullable: true currency: type: string nullable: true shippingStatus: anyOf: - $ref: '#/components/schemas/ShippingStatus' - type: 'null' serviceType: anyOf: - $ref: '#/components/schemas/ServiceType' - type: 'null' serviceName: type: string nullable: true selectedExpedition: type: string nullable: true selectedDelivery: type: string nullable: true courierGroup: type: string nullable: true vehicleType: anyOf: - $ref: '#/components/schemas/VehicleType' - type: 'null' bikeFuelType: type: string nullable: true packageHandover: anyOf: - $ref: '#/components/schemas/PackageHandover' - type: 'null' pickupSchedule: type: string format: date-time nullable: true storeLocationId: type: string nullable: true sender: $ref: '#/components/schemas/AddressOutput' delivery: $ref: '#/components/schemas/AddressOutput' package: $ref: '#/components/schemas/PackageOutput' driver: anyOf: - type: object properties: name: type: string nullable: true phone: type: string nullable: true photo: type: string nullable: true licensePlate: type: string nullable: true - type: 'null' insurance: type: boolean nullable: true insuranceFee: type: number format: double nullable: true insuranceAmount: type: number format: double nullable: true discountAmount: type: number format: double nullable: true discountPercentage: type: number format: double nullable: true distance: type: number format: double nullable: true trackingUrl: type: string nullable: true awb: type: string nullable: true description: Carrier waybill / tracking number. Populated after booking. orderNo: type: string nullable: true description: >- Carrier order number (KA `kj_order_id`, GoSend `orderNo`, RB merchant order id). bookingId: type: string nullable: true pickupNumber: type: string nullable: true description: KiriminAja Express pickup batch number. paymentId: type: string nullable: true paymentStatus: type: string nullable: true statusCode: type: integer nullable: true description: Provider-specific status code. cancellationReason: type: string nullable: true cancelledBy: type: string nullable: true cancelledSource: type: string nullable: true eventTimestamp: type: string nullable: true ShippingProvider: type: string enum: - gosend - kirimin_aja - ride_blitz - jne - custom description: >- Provider/courier code. `gosend`, `kirimin_aja`, and `ride_blitz` are externally integrated; `jne` is a passthrough placeholder; `custom` is for merchant-defined methods. ServiceType: type: string enum: - INSTANT - EXPRESS description: >- Service category. `INSTANT` = on-demand intra-city; `EXPRESS` = scheduled inter-city. VehicleType: type: string enum: - TWO_WHEEL - FOUR_WHEEL description: >- Vehicle requested for the pickup. `TWO_WHEEL` = motorcycle, `FOUR_WHEEL` = car. BikeFuelType: type: string enum: - regular - green description: >- RideBlitz fuel preference. `green` = electric fleet (lower emissions, may have limited availability). PackageHandover: type: string enum: - PICKUP - DROPOFF description: >- How the merchant hands the package to the carrier. `PICKUP` = courier picks up from the store, `DROPOFF` = merchant drops off at carrier hub. AddressInput: type: object required: - name - phone - address - coordinates properties: name: type: string maxLength: 255 phone: type: string maxLength: 32 description: >- E.164 (e.g. `+6281234567890`) recommended; bitbybit normalizes to `62…` for GoSend. email: type: string format: email address: type: string notes: type: string maxLength: 2000 city: type: string province: type: string country: type: string zip: type: string kecamatan: type: string kecamatanId: type: integer description: KiriminAja `kecamatan_id` — required for KA Express. kelurahan: type: string kelurahanId: type: integer description: KiriminAja `kelurahan_id` — required for KA Express. coordinates: $ref: '#/components/schemas/Coordinates' PackageInput: type: object required: - weight properties: weight: type: number format: double description: Weight in grams. length: type: number format: double description: Length in cm. width: type: number format: double description: Width in cm. height: type: number format: double description: Height in cm. itemName: type: string itemType: type: string description: >- KA categories: `fashion`, `peralatan_elektronik_gadget`, `pecah_belah`, `dokumen`, `dokumen_berharga`, etc. itemValue: type: number format: double description: Declared item value in IDR (used for insurance calculations). itemQty: type: integer minimum: 1 notes: type: string maxLength: 2000 ShippingStatus: type: string enum: - confirmed - allocated - out_for_pickup - picked - out_for_delivery - on_hold - cancelled - delivered - rejected - no_driver - awaiting - on_the_way_to_pickup - delivering - delivery_completed - canceled - processed_packages - shipped_packages - canceled_packages - finished_packages - returned_packages - return_finished_packages - created - midmile_pickup_done - midmile_pickup_failed - arrived_blitz_hub - allocation_failure - pickup_started - pickup_done - pickup_failed - pickup_failure - dropoff_started - dropoff_done - dropoff_failed - delivery_failure - cancelled_by_blitz - cancelled_by_business - returned_to_business description: >- Unified shipping status. Some values are provider-specific (e.g. `cancelled_by_blitz` is RideBlitz, `midmile_pickup_done` is KiriminAja Express). AddressOutput: type: object properties: name: type: string nullable: true phone: type: string nullable: true email: type: string nullable: true address: type: string nullable: true notes: type: string nullable: true city: type: string nullable: true province: type: string nullable: true country: type: string nullable: true zip: type: string nullable: true kecamatan: type: string nullable: true kecamatanId: type: integer nullable: true kelurahan: type: string nullable: true kelurahanId: type: integer nullable: true coordinates: anyOf: - $ref: '#/components/schemas/Coordinates' - type: 'null' PackageOutput: type: object properties: weight: type: number format: double nullable: true length: type: number format: double nullable: true width: type: number format: double nullable: true height: type: number format: double nullable: true itemName: type: string nullable: true itemType: type: string nullable: true itemValue: type: number format: double nullable: true itemQty: type: integer nullable: true notes: type: string nullable: true Error: type: object properties: error: type: object properties: code: type: string description: >- Machine-readable code, e.g. `VALIDATION_ERROR`, `NOT_FOUND`, `INTEGRATION_NOT_CONNECTED`, `PROVIDER_ERROR`, `BOOKING_FAILED`. message: type: string description: Human-readable error message. Coordinates: type: object required: - lat - lng properties: lat: type: number format: double minimum: -90 maximum: 90 lng: type: number format: double minimum: -180 maximum: 180 responses: ValidationError: description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: origin.districtId is required for KiriminAja Express Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Invalid API key securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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`). ````