> ## Documentation Index
> Fetch the complete documentation index at: https://docs.global-e.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit bonded information (Merchant to Global-e)
> Report, per product, how many units in an already-created parcel are bonded and how many are in free circulation, before the End-of-Day dispatch call.
This API is enabled per merchant account by Global-e. If it is not enabled for your account, the request returns `403 Forbidden` with no response body.
**Typical integration sequence.** These APIs may be used together when an export declaration or bonded reporting is required, but they are **independent endpoints** — none is a prerequisite for another.
1. [Get shipping documents](/api-reference/get-shipping-documents) — obtain the label and tracking number
2. **Submit bonded information** — report bonded vs free-circulation status per product *(when bonded reporting is required)*
3. [Get shipment information](/api-reference/get-shipment-information) — retrieve product, pricing and declaration header data *(when you need the data Global-e holds)*
4. Create the export document — your side, not a Global-e API
5. [Upload shipment documents](/api-reference/upload-shipment-documents) — upload the document and its reference to Global-e *(when a document must be attached)*
6. [Dispatch orders](/api-reference/dispatch-orders) — End of Day
Only steps 1 and 6 are universal. Steps 2 to 5 depend on the shipment type, the destination and your configuration. Where they apply, complete steps 2 and 5 **before End of Day / Dispatch orders**.
If bonded information is not submitted before End of Day, Global-e applies a default bonded status per item based on the parcel's fulfilment origin and destination. Values submitted through this API always override the default.
## OpenAPI
````yaml api-reference/specs/submitbondedinformation.yaml POST /api/merchant/parcels/bonded-information
openapi: 3.0.3
info:
title: SubmitBondedInformation
version: 1.0.0
description: >-
The Submit Bonded Information API lets you report the customs status of the
products inside a parcel that Global-e has already created — whether each
item is bonded or in free circulation. Global-e stores the status per
product against the parcel and uses it for customs and finance
reconciliation and, for UK outbound shipments, as the source for the carrier
bonded pre-alert.
servers:
- url: https://{globale_api_domain}
variables:
globale_api_domain:
default: globale_api_domain
description: Global-e API host, supplied to the merchant by Global-e.
security: []
tags:
- name: SubmitBondedInformation
x-page-title: SubmitBondedInformation
- name: 'Direction: Merchant → Global-e'
- name: 'Domain: Shipping'
paths:
/api/merchant/parcels/bonded-information:
post:
tags:
- SubmitBondedInformation
summary: Submit bonded information for a parcel
description: >-
Reports, per product, how many units in a parcel are bonded and how many
are in free circulation. Bonded goods are held under customs bond, so
import duty and VAT have not yet been paid on them; goods in free
circulation have already been cleared through customs.
The parcel is identified by the tracking number returned by
GetShippingDocuments. If any product line fails validation, Global-e
rejects the whole call and stores nothing.
Call this endpoint after the parcel has been picked and packed, and
before End of Day / DispatchOrders. Global-e accepts bonded information
only while the parcel is in an allowed status; a parcel that is no
longer in an allowed status is rejected with A711, and once its order
has been included in a reconciliation report the stored data is frozen
(A712).
If bonded information is not submitted before End of Day, Global-e
applies a default bonded status per item, based on the parcel's
fulfilment origin and destination. Values submitted through this API
always override the default.
Submitting again for the same tracking number is allowed while the
parcel is still in an allowed status: the most recent submission
replaces the stored status for the SKUs and quantities it covers, and
quantities it does not cover keep the status they already had.
This API is enabled per merchant account by Global-e. When it is not
enabled, the request returns 403 with no response body.
operationId: submitBondedInformation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitBondedInformationRequest'
examples:
singleStatus:
summary: All units of one SKU are bonded
value:
TrackingNumber: JD014600004882753258
Products:
- ProductSKU: Product123
IsBonded: true
Quantity: 2
skuSplit:
summary: One SKU split between bonded and free circulation
value:
TrackingNumber: JD014600004882753258
Products:
- ProductSKU: Product123
IsBonded: true
Quantity: 1
- ProductSKU: Product123
IsBonded: false
Quantity: 1
responses:
'200':
description: >-
The bonded information was validated and stored. Storage only —
finance reporting and the carrier pre-alert are produced
asynchronously afterwards.
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitBondedInformationResponse'
example:
Success: true
'400':
description: >-
The call was rejected and nothing was stored. Codes A700 (invalid
request body), A710 (tracking number not found), A711 (parcel not in
an allowed status), A712 (order already reconciled), A713 (invalid
product line), A716 (quantity exceeded).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
trackingNumberNotFound:
summary: A710 — tracking number not found
value:
Code: A710
Error: TrackingNumberNotFound
Description: Tracking number not found for this merchant.
parcelClosed:
summary: A711 — parcel not in an allowed status
value:
Code: A711
Error: ParcelClosed
Description: >-
The parcel is not in a status that accepts bonded
information.
invalidProductLine:
summary: A713 — invalid product line
value:
Code: A713
Error: InvalidProductLine
Description: IsBonded must be sent explicitly as true or false.
quantityExceeded:
summary: A716 — quantity exceeds the parcel
value:
Code: A716
Error: QuantityExceeded
Description: >-
Submitted quantity exceeds the quantity of this SKU in the
parcel.
'401':
description: Authentication credentials are missing, invalid, or expired (A702).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
Code: A702
Error: Unauthorized
Description: Authentication failed.
'403':
description: >-
The Submit Bonded Information API is not enabled for this merchant
account. No response body and no error code are returned. Contact
your Global-e account manager to have it enabled.
'500':
description: An unexpected error occurred in the Global-e system (A750).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
Code: A750
Error: InternalServerError
Description: An unexpected error occurred.
components:
schemas:
SubmitBondedInformationRequest:
type: object
title: SubmitBondedInformationRequest
required:
- TrackingNumber
- Products
properties:
TrackingNumber:
type: string
description: >-
Tracking number of the parcel, as returned by GetShippingDocuments.
A tracking number may cover more than one parcel, but all of those
parcels must belong to the same order.
example: JD014600004882753258
Products:
type: array
minItems: 1
description: >-
The product lines for this tracking number. At least one product
line must be provided. A SKU whose units are split between the two
customs statuses is sent as two lines for the same SKU — one bonded,
one free circulation — and their quantities are added together. See
the "One SKU split between bonded and free circulation" request
example.
items:
$ref: '#/components/schemas/BondedProduct'
SubmitBondedInformationResponse:
type: object
title: SubmitBondedInformationResponse
properties:
Success:
type: boolean
description: >-
Indicates that the bonded information was stored. Returned only with
HTTP 200, and always true. Failures are returned as an error
response instead.
example: true
ErrorResponse:
type: object
title: ErrorResponse
description: >-
General Global-e error envelope. Returned for every failure; the call is
rejected in full and nothing is stored.
properties:
Code:
type: string
description: Merchant-facing error code.
enum:
- A700
- A702
- A710
- A711
- A712
- A713
- A716
- A750
example: A710
Error:
type: string
description: Short error category.
example: TrackingNumberNotFound
Description:
type: string
description: Human-readable reason for the failure.
example: Tracking number not found for this merchant.
BondedProduct:
type: object
title: BondedProduct
required:
- ProductSKU
- IsBonded
- Quantity
properties:
ProductSKU:
type: string
description: >-
The product SKU as manifested in the parcel. Must be present in the
parcel identified by TrackingNumber. Matching is case-insensitive,
and matches either your primary or your secondary product code
depending on the product-code setting configured for your account
with Global-e.
example: Product123
IsBonded:
type: boolean
description: >-
The customs status of these units. true = bonded; false = free
circulation. Send true or false explicitly — Global-e rejects an
omitted or null value with A713.
example: true
Quantity:
type: integer
minimum: 1
description: >-
The number of units of this SKU that have the customs status given
in IsBonded. Must be greater than zero, and the total quantity
submitted for a SKU must not exceed the quantity of that SKU in the
parcel.
example: 1
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.